idnits 2.17.1 draft-levine-rfb-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 (August 2, 2010) is 5015 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Value' is mentioned on line 1641, but not defined -- Looks like a reference, but probably isn't: '0' on line 1275 -- Looks like a reference, but probably isn't: '2' on line 1130 -- Looks like a reference, but probably isn't: '3' on line 976 -- Looks like a reference, but probably isn't: '4' on line 1131 -- Looks like a reference, but probably isn't: '5' on line 844 -- Looks like a reference, but probably isn't: '6' on line 862 -- Looks like a reference, but probably isn't: '1' on line 1275 -- Looks like a reference, but probably isn't: '8' on line 1132 -- Looks like a reference, but probably isn't: '16' on line 1133 -- Looks like a reference, but probably isn't: '254' on line 1275 -- Looks like a reference, but probably isn't: '255' on line 1275 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force T. Richardson 3 Internet-Draft J. Levine 4 Intended status: Informational RealVNC Ltd. 5 Expires: February 3, 2011 August 2, 2010 7 The Remote Framebuffer Protocol 8 draft-levine-rfb-03 10 Abstract 12 RFB ("remote framebuffer") is a simple protocol for remote access to 13 graphical user interfaces which allows a client to view and control a 14 window system on another computer. Because it works at the 15 framebuffer level RFB is applicable to all windowing systems and 16 applications. This document describes the protocol used to 17 communicate between an RFB client and RFB server. RFB is the 18 protocol used in VNC, Virtual Network Computing. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on February 3, 2011. 37 Copyright Notice 39 Copyright (c) 2010 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Initial Connection . . . . . . . . . . . . . . . . . . . . . . 4 56 3. Display Protocol . . . . . . . . . . . . . . . . . . . . . . . 5 57 4. Input Protocol . . . . . . . . . . . . . . . . . . . . . . . . 6 58 5. Representation of Pixel Data . . . . . . . . . . . . . . . . . 6 59 6. Protocol Versions and Extensions . . . . . . . . . . . . . . . 7 60 7. Protocol Messages . . . . . . . . . . . . . . . . . . . . . . 7 61 7.1. Handshake Messages . . . . . . . . . . . . . . . . . . . . 8 62 7.1.1. ProtocolVersion Handshake . . . . . . . . . . . . . . 8 63 7.1.2. Security Handshake . . . . . . . . . . . . . . . . . . 9 64 7.1.3. SecurityResult Handshake . . . . . . . . . . . . . . . 10 65 7.2. Security Types . . . . . . . . . . . . . . . . . . . . . . 11 66 7.2.1. None . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 7.2.2. VNC Authentication . . . . . . . . . . . . . . . . . . 11 68 7.3. Initialization Messages . . . . . . . . . . . . . . . . . 12 69 7.3.1. ClientInit . . . . . . . . . . . . . . . . . . . . . . 12 70 7.3.2. ServerInit . . . . . . . . . . . . . . . . . . . . . . 12 71 7.4. Pixel Format Data Structure . . . . . . . . . . . . . . . 12 72 7.5. Client to Server Messages . . . . . . . . . . . . . . . . 14 73 7.5.1. SetPixelFormat . . . . . . . . . . . . . . . . . . . . 14 74 7.5.2. SetEncodings . . . . . . . . . . . . . . . . . . . . . 15 75 7.5.3. FramebufferUpdateRequest . . . . . . . . . . . . . . . 15 76 7.5.4. KeyEvent . . . . . . . . . . . . . . . . . . . . . . . 16 77 7.5.5. PointerEvent . . . . . . . . . . . . . . . . . . . . . 19 78 7.5.6. ClientCutText . . . . . . . . . . . . . . . . . . . . 19 79 7.6. Server to Client Messages . . . . . . . . . . . . . . . . 19 80 7.6.1. FramebufferUpdate . . . . . . . . . . . . . . . . . . 20 81 7.6.2. SetColorMapEntries . . . . . . . . . . . . . . . . . . 21 82 7.6.3. Bell . . . . . . . . . . . . . . . . . . . . . . . . . 21 83 7.6.4. ServerCutText . . . . . . . . . . . . . . . . . . . . 22 84 7.7. Encodings . . . . . . . . . . . . . . . . . . . . . . . . 22 85 7.7.1. Raw Encoding . . . . . . . . . . . . . . . . . . . . . 22 86 7.7.2. CopyRect Encoding . . . . . . . . . . . . . . . . . . 23 87 7.7.3. RRE Encoding . . . . . . . . . . . . . . . . . . . . . 23 88 7.7.4. Hextile Encoding . . . . . . . . . . . . . . . . . . . 24 89 7.7.5. TRLE encoding . . . . . . . . . . . . . . . . . . . . 26 90 7.7.6. ZRLE encoding . . . . . . . . . . . . . . . . . . . . 29 91 7.8. Pseudo-Encodings . . . . . . . . . . . . . . . . . . . . . 30 92 7.8.1. Cursor pseudo-encoding . . . . . . . . . . . . . . . . 30 93 7.8.2. DesktopSize pseudo-encoding . . . . . . . . . . . . . 31 94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 95 8.1. RFB Security Types . . . . . . . . . . . . . . . . . . . . 31 96 8.1.1. Registry Name . . . . . . . . . . . . . . . . . . . . 31 97 8.1.2. Registry Contents . . . . . . . . . . . . . . . . . . 31 98 8.2. Client to Server Message Types . . . . . . . . . . . . . . 32 99 8.2.1. Registry Name . . . . . . . . . . . . . . . . . . . . 32 100 8.2.2. Registry Contents . . . . . . . . . . . . . . . . . . 32 101 8.3. Server to Client Message Types . . . . . . . . . . . . . . 33 102 8.3.1. Registry Name . . . . . . . . . . . . . . . . . . . . 33 103 8.3.2. Registry Contents . . . . . . . . . . . . . . . . . . 33 104 8.4. RFB Encoding Types . . . . . . . . . . . . . . . . . . . . 34 105 8.4.1. Registry Name . . . . . . . . . . . . . . . . . . . . 34 106 8.4.2. Registry Contents . . . . . . . . . . . . . . . . . . 34 107 9. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 108 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 36 109 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36 110 11.1. References - Normative . . . . . . . . . . . . . . . . . . 36 111 11.2. References - Informative . . . . . . . . . . . . . . . . . 37 112 Appendix A. Differences in earlier protocol versions . . . . . . 37 113 A.1. Differences in the version 3.3 protocol . . . . . . . . . 37 114 A.2. Differences in the version 3.7 protocol . . . . . . . . . 38 115 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 38 116 B.1. Changes since -rfb-02 . . . . . . . . . . . . . . . . . . 38 117 B.2. Changes since -rfb-01 . . . . . . . . . . . . . . . . . . 38 118 B.3. Changes since -rfb-00 . . . . . . . . . . . . . . . . . . 38 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39 121 1. Introduction 123 RFB ("remote framebuffer") is a simple protocol for remote access to 124 graphical user interfaces. Because it works at the framebuffer level 125 it is applicable to all windowing systems and applications, including 126 X11, Windows and Macintosh. RFB is the protocol used in VNC (Virtual 127 Network Computing). The protocol is widely implemented and has had 128 fairly good interoperability. 130 The remote endpoint where the user sits (typically with a display, 131 keyboard, and pointer) is called the RFB client or viewer. The 132 endpoint where changes to the framebuffer originate (i.e., the 133 windowing system and applications) is known as the RFB server. 135 RFB is a "thin client" protocol. The emphasis in the design of the 136 RFB protocol is to make very few requirements of the client. In this 137 way, clients can run on the widest range of hardware, and the task of 138 implementing a client is made as simple as possible. 140 The protocol also makes the client stateless. If a client 141 disconnects from a given server and subsequently reconnects to that 142 same server, the state of the user interface is preserved. 143 Furthermore, a different client endpoint can be used to connect to 144 the same RFB server. At the new endpoint, the user will see exactly 145 the same graphical user interface as at the original endpoint. In 146 effect, the interface to the user's applications becomes completely 147 mobile. Wherever suitable network connectivity exists, the user can 148 access their own personal applications, and the state of these 149 applications is preserved between accesses from different locations. 150 This provides the user with a familiar, uniform view of the computing 151 infrastructure wherever they go. 153 The RFB protocol has evolved over the past decade, and has been 154 implemented several times, including at least one open source 155 version. This document describes the RFB protocol as actually 156 implemented, so that future implementers can interoperate with 157 existing clients and servers. 159 2. Initial Connection 161 An RFB server is typically a long-lived process that maintains the 162 state of a framebuffer. RFB clients typically connect, communicate 163 with the server for a period of time to use and manipulate the 164 framebuffer, then disconnect. A subsequent RFB session will then 165 pick up where a prior session left off, with the state of the 166 framebuffer intact. 168 An RFB client contacts the server on TCP port 5900. On systems with 169 multiple RFB servers, server N typically listens on port 5900+N, 170 analogous to the way that X Window servers listen on port 6000+N. 172 Some browser-based clients use a Java application to run the RFB 173 protocol. RFB servers sometimes provide a simple HTTP server on port 174 5800 that provides the requisite Java applet. 176 In some cases, the initial roles of the client and server are 177 reversed, with the RFB client listening on port 5500, and the RFB 178 server contacting the RFB client. Once the connection is 179 established, the two sides take their normal roles, with the RFB 180 server sending the first handshake message. 182 Note that the only port number assigned by IANA for RFB is port 5900, 183 so RFB clients and servers should avoid using other port numbers 184 unless they are communicating with servers or clients known to use 185 the non-standard ports. 187 3. Display Protocol 189 The display side of the protocol is based around a single graphics 190 primitive: "put a rectangle of pixel data at a given x,y position". 191 This might seem an inefficient way of drawing many user interface 192 components. However, allowing various different encodings for the 193 pixel data gives us a large degree of flexibility in how to trade off 194 various parameters such as network bandwidth, client drawing speed 195 and server processing speed. 197 A sequence of these rectangles makes a framebuffer update (or simply 198 update). An update represents a change from one valid framebuffer 199 state to another, so in some ways is similar to a frame of video. 200 The rectangles in an update are usually but not always disjoint. 202 The update protocol is demand-driven by the client. That is, an 203 update is only sent from the server to the client in response to an 204 explicit request from the client. This gives the protocol an 205 adaptive quality. The slower the client and the network are, the 206 lower the rate of updates. With typical applications, changes to the 207 same area of the framebuffer tend to happen soon after one another. 208 With a slow client or network, transient states of the framebuffer 209 can be ignored, resulting in less network traffic and less drawing 210 for the client. 212 After the initial handshake sequence, the protocol is asynchronous, 213 with each side sending messages as needed. The server must not send 214 unsolicited updates. An update must only be sent in response to a 215 request from the client. When several requests from the client are 216 outstanding, a single update from the server may satisfy all of them. 218 4. Input Protocol 220 The input side of the protocol is based on a standard workstation 221 model of a keyboard and multi-button pointing device. Input events 222 are simply sent to the server by the client whenever the user presses 223 a key or pointer button, or whenever the pointing device is moved. 224 These input events can also be synthesised from other non-standard 225 I/O devices. For example, a pen-based handwriting recognition engine 226 might generate keyboard events. 228 5. Representation of Pixel Data 230 Initial interaction between the RFB client and server involves a 231 negotiation of the format and encoding of the pixel data that will be 232 sent. This negotiation has been designed to make the job of the 233 client as easy as possible. The server must always be able to supply 234 pixel data in the form the client wants. However if the client is 235 able to cope equally with several different formats or encodings, it 236 may choose one which is easier for the server to produce. 238 Pixel format refers to the representation of individual colors by 239 pixel values. The most common pixel formats are 24-bit or 16-bit 240 "true color", where bit-fields within the pixel value translate 241 directly to red, green and blue intensities, and 8-bit "color map" 242 (palette) where the pixel values are indices into a 256 entry table 243 that contains the actual RGB intensities. 245 Encoding refers to the way that a rectangle of pixel data will be 246 sent to the client. Every rectangle of pixel data is prefixed by a 247 header giving the X,Y position of the rectangle on the screen, the 248 width and height of the rectangle, and an encoding type which 249 specifies the encoding of the pixel data. The data itself then 250 follows using the specified encoding. 252 The encoding types defined at present are: Raw, CopyRect, RRE, TRLE, 253 Hextile, and ZRLE. In practice current servers use the ZRLE, TRLE, 254 and CopyRect encodings since they provide the best compression for 255 typical desktops. Clients generally also support Hextile, which was 256 often used by older RFB servers that didn't support TRLE. See 257 Section 7.7 for a description of each of the encodings. 259 6. Protocol Versions and Extensions 261 The RFB protocol has evolved through three published versions: 3.3, 262 3.7, and 3.8. This document primarily documents the final version 263 3.8; differences from the earlier versions, which are minor, are 264 described in Appendix A. Under no circumstances should an 265 implementation use a protocol version number other than one defined 266 in this document. Over the years, different implementations of RFB 267 have attempted to use different version numbers to add undocumented 268 extensions, with the result being that to interoperate, any unknown 269 3.x version must be treated as 3.3, so it is not possible to add a 270 3.9 or higher version in a backward compatible fashion. Future 271 evolution of RFB will use 4.x version numbers. 273 It is not necessary to change the protocol version number to extend 274 the protocol. The protocol can be extended within an existing 275 version by: 277 New encodings A new encoding type can be added to the protocol 278 relatively easily while maintaining compatibility with existing 279 clients and servers. Existing servers will simply ignore requests 280 for a new encoding which they don't support. Existing clients 281 will never request the new encoding so will never see rectangles 282 encoded that way. 284 Pseudo encodings In addition to genuine encodings, a client can 285 request a "pseudo-encoding" to declare to the server that it 286 supports a certain extension to the protocol. A server which does 287 not support the extension will simply ignore the pseudo-encoding. 288 Note that this means the client must assume that the server does 289 not support the extension until it gets some extension-specific 290 confirmation from the server. See Section 7.8 for a description 291 of current pseudo-encodings. 293 New security types Adding a new security type gives full flexibility 294 in modifying the behavior of the protocol without sacrificing 295 compatibility with existing clients and servers. A client and 296 server which agree on a new security type can effectively talk 297 whatever protocol they like after that - it doesn't necessarily 298 have to be anything like the RFB protocol. 300 See Section 8 for information on obtaining an ID for a new encoding 301 or security type. 303 7. Protocol Messages 305 The RFB protocol can operate over any reliable transport, either 306 byte-stream or message-based. It usually operates over a TCP/IP 307 connection. There are three stages to the protocol. First is the 308 handshaking phase, the purpose of which is to agree upon the protocol 309 version and the type of security to be used. The second stage is an 310 initialisation phase where the client and server exchange ClientInit 311 and ServerInit messages. The final stage is the normal protocol 312 interaction. The client can send whichever messages it wants, and 313 may receive messages from the server as a result. All these messages 314 begin with a message-type byte, followed by message-specific data. 316 The following descriptions of protocol messages use the basic types 317 U8, U16, U32, S8, S16, and S32. These represent respectively 8, 16 318 and 32-bit unsigned integers and 8, 16 and 32-bit signed integers. 319 All multiple byte integers (other than pixel values themselves) are 320 in big endian order (most significant byte first). Some messages use 321 arrays of the basic types, with the number of entries in the array 322 determined from fields preceding the array. 324 The type PIXEL means a pixel value of bytesPerPixel bytes, where 325 bytesPerPixel is the number of bits-per-pixel divided by 8. The 326 bits-per-pixel is agreed by the client and server, either in the 327 ServerInit message (Section 7.3.2) or a SetPixelFormat message 328 (Section 7.5.1). See Section 7.4 for the detailed description of the 329 pixel format. 331 Several message formats include padding bits or bytes. For maximum 332 compatibility, messages should be generated with padding set to zero, 333 but message recipients should not assume padding has any particular 334 value. 336 7.1. Handshake Messages 338 When an RFB client and server first connect, they exchange a sequence 339 of handshake messages that determine the protocol version, what type 340 of connection security if any to use, a password check if the 341 security type requires it, and some initialization information. 343 7.1.1. ProtocolVersion Handshake 345 Handshaking begins by the server sending the client a ProtocolVersion 346 message. This lets the client know which is the highest RFB protocol 347 version number supported by the server. The client then replies with 348 a similar message giving the version number of the protocol which 349 should actually be used (which may be different to that quoted by the 350 server). A client should never request a protocol version higher 351 than that offered by the server. It is intended that both clients 352 and servers may provide some level of backwards compatibility by this 353 mechanism. 355 The only published protocol versions at this time are 3.3, 3.7, and 356 3.8. Other version numbers are reported by some servers and clients, 357 but should be interpreted as 3.3 since they do not implement the 358 different handshake in 3.7 or 3.8. Addition of a new encoding or 359 pseudo-encoding type does not require a change in protocol version, 360 since a server can simply ignore encodings it does not understand. 362 The ProtocolVersion message consists of 12 bytes interpreted as a 363 string of ASCII characters in the format "RFB xxx.yyy\n" where xxx 364 and yyy are the major and minor version numbers, left padded with 365 zeros: 367 RFB 003.008\n (hex 52 46 42 20 30 30 33 2e 30 30 38 0a) 369 7.1.2. Security Handshake 371 Once the protocol version has been decided, the server and client 372 must agree on the type of security to be used on the connection. The 373 server lists the security types which it supports: 375 +--------------------------+-------------+--------------------------+ 376 | No. of bytes | Type | Description | 377 | | [Value] | | 378 +--------------------------+-------------+--------------------------+ 379 | 1 | U8 | number-of-security-types | 380 | number-of-security-types | U8 array | security-types | 381 +--------------------------+-------------+--------------------------+ 383 If the server listed at least one valid security type supported by 384 the client, the client sends back a single byte indicating which 385 security type is to be used on the connection: 387 +--------------+--------------+---------------+ 388 | No. of bytes | Type [Value] | Description | 389 +--------------+--------------+---------------+ 390 | 1 | U8 | security-type | 391 +--------------+--------------+---------------+ 393 If number-of-security-types is zero, then for some reason the 394 connection failed (e.g. the server cannot support the desired 395 protocol version). This is followed by a string describing the 396 reason (where a string is specified as a length followed by that many 397 ASCII characters): 399 +---------------+--------------+---------------+ 400 | No. of bytes | Type [Value] | Description | 401 +---------------+--------------+---------------+ 402 | 4 | U32 | reason-length | 403 | reason-length | U8 array | reason-string | 404 +---------------+--------------+---------------+ 406 The server closes the connection after sending the reason-string. 408 The security types defined in this document are: 410 +--------+--------------------+ 411 | Number | Name | 412 +--------+--------------------+ 413 | 0 | Invalid | 414 | 1 | None | 415 | 2 | VNC Authentication | 416 +--------+--------------------+ 418 Other security types exist but are not publicly documented. 420 Once the security-type has been decided, data specific to that 421 security-type follows (see Section 7.2 for details). At the end of 422 the security handshaking phase, the protocol normally continues with 423 the SecurityResult message. 425 Note that after the security handshaking phase, it is possible that 426 further communication is over an encrypted or otherwise altered 427 channel if the two ends agree on an extended security type beyond the 428 ones described here. 430 7.1.3. SecurityResult Handshake 432 The server sends a word to inform the client whether the security 433 handshaking was successful. 435 +--------------+--------------+-------------+ 436 | No. of bytes | Type [Value] | Description | 437 +--------------+--------------+-------------+ 438 | 4 | U32 | status: | 439 | | 0 | OK | 440 | | 1 | failed | 441 +--------------+--------------+-------------+ 443 If successful, the protocol passes to the initialization phase 444 (Section 7.3). 446 If unsuccessful, the server sends a string describing the reason for 447 the failure, and then closes the connection: 449 +---------------+--------------+---------------+ 450 | No. of bytes | Type [Value] | Description | 451 +---------------+--------------+---------------+ 452 | 4 | U32 | reason-length | 453 | reason-length | U8 array | reason-string | 454 +---------------+--------------+---------------+ 456 7.2. Security Types 458 Two security types are defined here. 460 7.2.1. None 462 No authentication is needed. The protocol continues with the 463 SecurityResult message. 465 7.2.2. VNC Authentication 467 VNC authentication is to be used. The server sends a random 16-byte 468 challenge: 470 +--------------+--------------+-------------+ 471 | No. of bytes | Type [Value] | Description | 472 +--------------+--------------+-------------+ 473 | 16 | U8 | challenge | 474 +--------------+--------------+-------------+ 476 The client encrypts the challenge with DES, using a password supplied 477 by the user as the key. To form the key, the password is truncated 478 to eight characters, or padded with null bytes on the right. The 479 client then sends the resulting 16-byte response: 481 +--------------+--------------+-------------+ 482 | No. of bytes | Type [Value] | Description | 483 +--------------+--------------+-------------+ 484 | 16 | U8 | response | 485 +--------------+--------------+-------------+ 487 The protocol continues with the SecurityResult message. 489 This type of authentication is known to be cryptographically weak and 490 is not intended for use on untrusted networks. Many implementations 491 will want to use stronger security, such as running the session over 492 an encrypted channel provided by IPSEC [RFC4301] or SSH [RFC4254]. 494 7.3. Initialization Messages 496 Once the client and server agree on and perhaps validate a security 497 type, the protocol passes to the initialization stage. The client 498 sends a ClientInit message. Then the server sends a ServerInit 499 message. 501 7.3.1. ClientInit 503 +--------------+--------------+-------------+ 504 | No. of bytes | Type [Value] | Description | 505 +--------------+--------------+-------------+ 506 | 1 | U8 | shared-flag | 507 +--------------+--------------+-------------+ 509 Shared-flag is non-zero (true) if the server should try to share the 510 desktop by leaving other clients connected, zero (false) if it should 511 give exclusive access to this client by disconnecting all other 512 clients. 514 7.3.2. ServerInit 516 After receiving the ClientInit message, the server sends a ServerInit 517 message. This tells the client the width and height of the server's 518 framebuffer, its pixel format and the name associated with the 519 desktop: 521 +--------------+--------------+------------------------------+ 522 | No. of bytes | Type [Value] | Description | 523 +--------------+--------------+------------------------------+ 524 | 2 | U16 | framebuffer-width in pixels | 525 | 2 | U16 | framebuffer-height in pixels | 526 | 16 | PIXEL_FORMAT | server-pixel-format | 527 | 4 | U32 | name-length | 528 | name-length | U8 array | name-string | 529 +--------------+--------------+------------------------------+ 531 Server-pixel-format specifies the server's natural pixel format. 532 This pixel format will be used unless the client requests a different 533 format using the SetPixelFormat message (Section 7.5.1). 535 7.4. Pixel Format Data Structure 537 Several server to client messages include a PIXEL_FORMAT, a 16 byte 538 structure that describes the way a pixel is transmited. 540 +--------------+--------------+-----------------+ 541 | No. of bytes | Type [Value] | Description | 542 +--------------+--------------+-----------------+ 543 | 1 | U8 | bits-per-pixel | 544 | 1 | U8 | depth | 545 | 1 | U8 | big-endian-flag | 546 | 1 | U8 | true-color-flag | 547 | 2 | U16 | red-max | 548 | 2 | U16 | green-max | 549 | 2 | U16 | blue-max | 550 | 1 | U8 | red-shift | 551 | 1 | U8 | green-shift | 552 | 1 | U8 | blue-shift | 553 | 3 | | padding | 554 +--------------+--------------+-----------------+ 556 Bits-per-pixel is the number of bits used for each pixel value on the 557 wire. This must be greater than or equal to the depth which is the 558 number of useful bits in the pixel value. Currently bits-per-pixel 559 must be 8, 16 or 32. Big-endian-flag is non-zero (true) if multi- 560 byte pixels are interpreted as big endian. Although the depth should 561 be consistent with the bits-per-pixel and the various -max values, 562 clients do not use it when interpreting pixel data. 564 If true-color-flag is non-zero (true) then the last six items specify 565 how to extract the red, green and blue intensities from the pixel 566 value. Red-max is the maximum red value and must be 2^N - 1 where N 567 is the number of bits used for red. Note the -max values are always 568 in big endian order. Red-shift is the number of shifts needed to get 569 the red value in a pixel to the least significant bit. Green-max, 570 green-shift and blue-max, blue-shift are similar for green and blue. 571 For example, to find the red value (between 0 and red-max) from a 572 given pixel, do the following: 574 o Swap the pixel value according to big-endian-flag, e.g., if big- 575 endian-flag is zero (false) and host byte order is big endian, 576 then swap. 578 o Shift right by red-shift. 580 o AND with red-max (in host byte order). 582 If true-color-flag is zero (false) then the server uses pixel values 583 which are not directly composed from the red, green and blue 584 intensities, but which serve as indices into a color map. Entries in 585 the color map are set by the server using the SetColorMapEntries 586 message (See Section 7.6.2). 588 7.5. Client to Server Messages 590 The client to server message types defined in this document are: 592 +--------+--------------------------+ 593 | Number | Name | 594 +--------+--------------------------+ 595 | 0 | SetPixelFormat | 596 | 2 | SetEncodings | 597 | 3 | FramebufferUpdateRequest | 598 | 4 | KeyEvent | 599 | 5 | PointerEvent | 600 | 6 | ClientCutText | 601 +--------+--------------------------+ 603 Other message types exist but are not publicly documented. Before 604 sending a message other than those described in this document a 605 client must have determined that the server supports the relevant 606 extension by receiving an appropriate extension-specific confirmation 607 from the server. 609 7.5.1. SetPixelFormat 611 Sets the format in which pixel values should be sent in 612 FramebufferUpdate messages. If the client does not send a 613 SetPixelFormat message then the server sends pixel values in its 614 natural format as specified in the ServerInit message 615 (Section 7.3.2). 617 If true-color-flag is zero (false) then this indicates that a "color 618 map" is to be used. The server can set any of the entries in the 619 color map using the SetColorMapEntries message (Section 7.6.2). 620 Immediately after the client has sent this message the contents of 621 the color map are undefined, even if entries had previously been set 622 by the server. 624 +--------------+--------------+--------------+ 625 | No. of bytes | Type [Value] | Description | 626 +--------------+--------------+--------------+ 627 | 1 | U8 [0] | message-type | 628 | 3 | | padding | 629 | 16 | PIXEL_FORMAT | pixel-format | 630 +--------------+--------------+--------------+ 632 PIXEL_FORMAT is as described in Section 7.4. 634 7.5.2. SetEncodings 636 Sets the encoding types in which pixel data can be sent by the 637 server. The order of the encoding types given in this message is a 638 hint by the client as to its preference (the first encoding specified 639 being most preferred). The server may or may not choose to make use 640 of this hint. Pixel data may always be sent in raw encoding even if 641 not specified explicitly here. 643 In addition to genuine encodings, a client can request "pseudo- 644 encodings" to declare to the server that it supports certain 645 extensions to the protocol. A server which does not support the 646 extension will simply ignore the pseudo-encoding. Note that this 647 means the client must assume that the server does not support the 648 extension until it gets some extension-specific confirmation from the 649 server. 651 See Section 7.7 for a description of each encoding and Section 7.8 652 for the meaning of pseudo-encodings. 654 +--------------+--------------+---------------------+ 655 | No. of bytes | Type [Value] | Description | 656 +--------------+--------------+---------------------+ 657 | 1 | U8 [2] | message-type | 658 | 1 | | padding | 659 | 2 | U16 | number-of-encodings | 660 +--------------+--------------+---------------------+ 662 followed by number-of-encodings repetitions of the following: 664 +--------------+--------------+---------------+ 665 | No. of bytes | Type [Value] | Description | 666 +--------------+--------------+---------------+ 667 | 4 | S32 | encoding-type | 668 +--------------+--------------+---------------+ 670 7.5.3. FramebufferUpdateRequest 672 Notifies the server that the client is interested in the area of the 673 framebuffer specified by x-position, y-position, width and height. 674 The server usually responds to a FramebufferUpdateRequest by sending 675 a FramebufferUpdate. A single FramebufferUpdate may be sent in reply 676 to several FramebufferUpdateRequests. 678 The server assumes that the client keeps a copy of all parts of the 679 framebuffer in which it is interested. This means that normally the 680 server only needs to send incremental updates to the client. 682 If the client has lost the contents of a particular area which it 683 needs, then the client sends a FramebufferUpdateRequest with 684 incremental set to zero (false). This requests that the server send 685 the entire contents of the specified area as soon as possible. The 686 area will not be updated using the CopyRect encoding. 688 If the client has not lost any contents of the area in which it is 689 interested, then it sends a FramebufferUpdateRequest with incremental 690 set to non-zero (true). If and when there are changes to the 691 specified area of the framebuffer, the server will send a 692 FramebufferUpdate. Note that there may be an indefinite period 693 between the FramebufferUpdateRequest and the FramebufferUpdate. 695 In the case of a fast client, the client may want to regulate the 696 rate at which it sends incremental FramebufferUpdateRequests to avoid 697 excessive network traffic. 699 +--------------+--------------+--------------+ 700 | No. of bytes | Type [Value] | Description | 701 +--------------+--------------+--------------+ 702 | 1 | U8 [3] | message-type | 703 | 1 | U8 | incremental | 704 | 2 | U16 | x-position | 705 | 2 | U16 | y-position | 706 | 2 | U16 | width | 707 | 2 | U16 | height | 708 +--------------+--------------+--------------+ 710 7.5.4. KeyEvent 712 A key press or release. Down-flag is non-zero (true) if the key is 713 now pressed, zero (false) if it is now released. The key itself is 714 specified using the "keysym" values defined by the X Window System, 715 even if the client or server is not running X. 717 +--------------+--------------+--------------+ 718 | No. of bytes | Type [Value] | Description | 719 +--------------+--------------+--------------+ 720 | 1 | U8 [4] | message-type | 721 | 1 | U8 | down-flag | 722 | 2 | | padding | 723 | 4 | U32 | key | 724 +--------------+--------------+--------------+ 726 For most ordinary keys, the keysym is the same as the corresponding 727 ASCII value. For full details, see [XLIBREF] or see the header file 728 in the X Window System distribution. Some other 729 common keys are: 731 +-----------------+--------------------+ 732 | Key name | Keysym value (hex) | 733 +-----------------+--------------------+ 734 | BackSpace | 0xff08 | 735 | Tab | 0xff09 | 736 | Return or Enter | 0xff0d | 737 | Escape | 0xff1b | 738 | Insert | 0xff63 | 739 | Delete | 0xffff | 740 | Home | 0xff50 | 741 | End | 0xff57 | 742 | Page Up | 0xff55 | 743 | Page Down | 0xff56 | 744 | Left | 0xff51 | 745 | Up | 0xff52 | 746 | Right | 0xff53 | 747 | Down | 0xff54 | 748 | F1 | 0xffbe | 749 | F2 | 0xffbf | 750 | F3 | 0xffc0 | 751 | F4 | 0xffc1 | 752 | ... | ... | 753 | F12 | 0xffc9 | 754 | Shift (left) | 0xffe1 | 755 | Shift (right) | 0xffe2 | 756 | Control (left) | 0xffe3 | 757 | Control (right) | 0xffe4 | 758 | Meta (left) | 0xffe7 | 759 | Meta (right) | 0xffe8 | 760 | Alt (left) | 0xffe9 | 761 | Alt (right) | 0xffea | 762 +-----------------+--------------------+ 764 The interpretation of keysyms is a complex area. In order to be as 765 widely interoperable as possible the following guidelines should be 766 followed: 768 o The "shift state" (i.e. whether either of the Shift keysyms is 769 down) should only be used as a hint when interpreting a keysym. 770 For example, on a US keyboard the '#' character is shifted, but on 771 a UK keyboard it is not. A server with a US keyboard receiving a 772 '#' character from a client with a UK keyboard will not have been 773 sent any shift presses. In this case, it is likely that the 774 server will internally need to simulate a shift press on its local 775 system in order to get a '#' character and not a '3'. 777 o The difference between upper and lower case keysyms is 778 significant. This is unlike some of the keyboard processing in 779 the X Window System which treats them as the same. For example, a 780 server receiving an uppercase 'A' keysym without any shift presses 781 should interpret it as an uppercase 'A'. Again this may involve 782 an internal simulated shift press. 784 o Servers should ignore "lock" keysyms such as CapsLock and NumLock 785 where possible. Instead they should interpret each character- 786 based keysym according to its case. 788 o Unlike Shift, the state of modifier keys such as Control and Alt 789 should be taken as modifying the interpretation of other keysyms. 790 Note that there are no keysyms for ASCII control characters such 791 as Ctrl-A - these should be generated by clients sending a Control 792 press followed by an 'a' press. 794 o On a client where modifiers like Control and Alt can also be used 795 to generate character-based keysyms, the client may need to send 796 extra "release" events in order that the keysym is interpreted 797 correctly. For example, on a German PC keyboard, Ctrl-Alt-Q 798 generates the '@' character. In this case, the client needs to 799 send simulated release events for Control and Alt in order that 800 the '@' character is interpreted correctly, since Ctrl-Alt-@ may 801 mean something completely different to the server. 803 o There is no universal standard for "backward tab" in the X Window 804 System. On some systems shift+tab gives the keysym 805 "ISO_Left_Tab", on others it gives a private "BackTab" keysym and 806 on others it gives "Tab" and applications tell from the shift 807 state that it means backward-tab rather than forward-tab. In the 808 RFB protocol the latter approach is preferred. Clients should 809 generate a shifted Tab rather than ISO_Left_Tab. However, to be 810 backwards-compatible with existing clients, servers should also 811 recognise ISO_Left_Tab as meaning a shifted Tab. 813 o Modern versions of the X Window system handle keysyms for Unicode 814 characters, consisting of the Unicode character with the hex 815 1000000 bit set. For maximum compatibility, if a key has both a 816 Unicode and a legacy encoding, clients should send the legacy 817 encoding. 819 o Some systems give a special interpretation to key combinations 820 such as Ctrl-Alt-Delete. RFB clients typically provide a menu or 821 toolbar function to send such key combinations. The RFB protocol 822 does not treat them specially; to send Ctrl-Alt-Delete, the client 823 sends the key presses for left or right Control, left or right 824 Alt, and Delete, followed by the key releases. Many RFB servers 825 accept Shift-Ctrl-Alt-Delete as a synonym for Ctrl-Alt-Delete that 826 can be entered directly from the keyboard. 828 7.5.5. PointerEvent 830 Indicates either pointer movement or a pointer button press or 831 release. The pointer is now at ( x-position, y-position), and the 832 current state of buttons 1 to 8 are represented by bits 0 to 7 of 833 button-mask respectively, 0 meaning up, 1 meaning down (pressed). 835 On a conventional mouse, buttons 1, 2 and 3 correspond to the left, 836 middle and right buttons on the mouse. On a wheel mouse, each step 837 of the wheel upwards is represented by a press and release of button 838 4, and each step downwards is represented by a press and release of 839 button 5. 841 +--------------+--------------+--------------+ 842 | No. of bytes | Type [Value] | Description | 843 +--------------+--------------+--------------+ 844 | 1 | U8 [5] | message-type | 845 | 1 | U8 | button-mask | 846 | 2 | U16 | x-position | 847 | 2 | U16 | y-position | 848 +--------------+--------------+--------------+ 850 7.5.6. ClientCutText 852 RFB provides limited support for synchronizing the "cut buffer" of 853 selected text between client and server. This message tells the 854 server that the client has new ISO 8859-1 (Latin-1) text in its cut 855 buffer. Ends of lines are represented by the newline character (hex 856 0a) alone. No carriage-return (hex 0d) is used. There is no way to 857 transfer text outside the Latin-1 character set. 859 +--------------+--------------+--------------+ 860 | No. of bytes | Type [Value] | Description | 861 +--------------+--------------+--------------+ 862 | 1 | U8 [6] | message-type | 863 | 3 | | padding | 864 | 4 | U32 | length | 865 | length | U8 array | text | 866 +--------------+--------------+--------------+ 868 7.6. Server to Client Messages 870 The server to client message types defined in this document are: 872 +--------+--------------------+ 873 | Number | Name | 874 +--------+--------------------+ 875 | 0 | FramebufferUpdate | 876 | 1 | SetColorMapEntries | 877 | 2 | Bell | 878 | 3 | ServerCutText | 879 +--------+--------------------+ 881 Other private message types exist but are not publicly documented. 882 Before sending a message other than those described in this document 883 a server must have determined that the client supports the relevant 884 extension by receiving some extension-specific confirmation from the 885 client - usually a request for a given pseudo-encoding. 887 7.6.1. FramebufferUpdate 889 A framebuffer update consists of a sequence of rectangles of pixel 890 data which the client should put into its framebuffer. It is sent in 891 response to a FramebufferUpdateRequest from the client. Note that 892 there may be an indefinite period between the 893 FramebufferUpdateRequest and the FramebufferUpdate. 895 +--------------+--------------+----------------------+ 896 | No. of bytes | Type [Value] | Description | 897 +--------------+--------------+----------------------+ 898 | 1 | U8 [0] | message-type | 899 | 1 | | padding | 900 | 2 | U16 | number-of-rectangles | 901 +--------------+--------------+----------------------+ 903 This header is followed by number-of-rectangles rectangles of pixel 904 data. Each rectangle starts with a rectangle header: 906 +--------------+--------------+---------------+ 907 | No. of bytes | Type [Value] | Description | 908 +--------------+--------------+---------------+ 909 | 2 | U16 | x-position | 910 | 2 | U16 | y-position | 911 | 2 | U16 | width | 912 | 2 | U16 | height | 913 | 4 | S32 | encoding-type | 914 +--------------+--------------+---------------+ 916 The rectangle header is followed by the pixel data in the specified 917 encoding. See Section 7.7 for the format of the data for each 918 encoding and Section 7.8 for the meaning of pseudo-encodings. 920 7.6.2. SetColorMapEntries 922 When the pixel format uses a "color map", this message tells the 923 client that the specified pixel values should be mapped to the given 924 RGB values. Note that this message may only update part of the color 925 map. This message should not be sent by the server until after the 926 client has sent at least one FramebufferUpdateRequest, and only when 927 the agreed pixel format uses a color map. 929 Color map values are always 16 bits, with the range of values running 930 from 0 to 65535, regardless of the display hardware in use. The 931 color map value for white, for example, is 65535,65535,65535. 933 The message starts with a header describing the range of colormap 934 entries to be updated. 936 +--------------+--------------+------------------+ 937 | No. of bytes | Type [Value] | Description | 938 +--------------+--------------+------------------+ 939 | 1 | U8 [1] | message-type | 940 | 1 | | padding | 941 | 2 | U16 | first-color | 942 | 2 | U16 | number-of-colors | 943 +--------------+--------------+------------------+ 945 This header is followed by number-of-colors RGB values, each of which 946 is in this format: 948 +--------------+--------------+-------------+ 949 | No. of bytes | Type [Value] | Description | 950 +--------------+--------------+-------------+ 951 | 2 | U16 | red | 952 | 2 | U16 | green | 953 | 2 | U16 | blue | 954 +--------------+--------------+-------------+ 956 7.6.3. Bell 958 Make an audible signal on the client if it provides one. 960 +--------------+--------------+--------------+ 961 | No. of bytes | Type [Value] | Description | 962 +--------------+--------------+--------------+ 963 | 1 | U8 [2] | message-type | 964 +--------------+--------------+--------------+ 966 7.6.4. ServerCutText 968 The server has new ISO 8859-1 (Latin-1) text in its cut buffer. Ends 969 of lines are represented by the newline character (hex 0a) alone. No 970 carriage-return (hex 0d) is used. There is no way to transfer text 971 outside the Latin-1 character set. 973 +--------------+--------------+--------------+ 974 | No. of bytes | Type [Value] | Description | 975 +--------------+--------------+--------------+ 976 | 1 | U8 [3] | message-type | 977 | 3 | | padding | 978 | 4 | U32 | length | 979 | length | U8 array | text | 980 +--------------+--------------+--------------+ 982 7.7. Encodings 984 The encodings defined in this document are: 986 +--------+-----------------------------+ 987 | Number | Name | 988 +--------+-----------------------------+ 989 | 0 | Raw | 990 | 1 | CopyRect | 991 | 2 | RRE | 992 | 5 | Hextile | 993 | 15 | TRLE | 994 | 16 | ZRLE | 995 | -239 | Cursor pseudo-encoding | 996 | -223 | DesktopSize pseudo-encoding | 997 +--------+-----------------------------+ 999 Other encoding types exist but are not publicly documented. 1001 7.7.1. Raw Encoding 1003 The simplest encoding type is raw pixel data. In this case the data 1004 consists of width*height pixel values (where width and height are the 1005 width and height of the rectangle). The values simply represent each 1006 pixel in left-to-right scan line order. All RFB clients must be able 1007 to handle pixel data in this raw encoding, and RFB servers should 1008 only produce raw encoding unless the client specifically asks for 1009 some other encoding type. 1011 +----------------------------+--------------+-------------+ 1012 | No. of bytes | Type [Value] | Description | 1013 +----------------------------+--------------+-------------+ 1014 | width*height*bytesPerPixel | PIXEL array | pixels | 1015 +----------------------------+--------------+-------------+ 1017 7.7.2. CopyRect Encoding 1019 The CopyRect (copy rectangle) encoding is a very simple and efficient 1020 encoding which can be used when the client already has the same pixel 1021 data elsewhere in its framebuffer. The encoding on the wire simply 1022 consists of an X,Y coordinate. This gives a position in the 1023 framebuffer from which the client can copy the rectangle of pixel 1024 data. This can be used in a variety of situations, the most common 1025 of which are when the user moves a window across the screen, and when 1026 the contents of a window are scrolled. 1028 +--------------+--------------+----------------+ 1029 | No. of bytes | Type [Value] | Description | 1030 +--------------+--------------+----------------+ 1031 | 2 | U16 | src-x-position | 1032 | 2 | U16 | src-y-position | 1033 +--------------+--------------+----------------+ 1035 For maximum compatibility the source rectangle of a CopyRect should 1036 not include pixels updated by previous entries in the same 1037 FramebufferUpdate message. 1039 7.7.3. RRE Encoding 1041 Note: RRE encoding is obsolescent. In general, ZRLE and TRLE 1042 encoding are more compact. 1044 RRE stands for rise-and-run-length encoding. As its name implies, it 1045 is essentially a two-dimensional analogue of run-length encoding. 1046 RRE-encoded rectangles arrive at the client in a form which can be 1047 rendered immediately by the simplest of graphics engines. RRE is not 1048 appropriate for complex desktops, but can be useful in some 1049 situations. 1051 The basic idea behind RRE is the partitioning of a rectangle of pixel 1052 data into rectangular subregions (subrectangles) each of which 1053 consists of pixels of a single value and the union of which comprises 1054 the original rectangular region. The near-optimal partition of a 1055 given rectangle into such subrectangles is relatively easy to 1056 compute. 1058 The encoding consists of a background pixel value, Vb (typically the 1059 most prevalent pixel value in the rectangle) and a count N, followed 1060 by a list of N subrectangles, each of which consists of a tuple 1061 where v (which should be different from Vb) is the pixel 1062 value, (x,y) are the coordinates of the subrectangle relative to the 1063 top-left corner of the rectangle, and (w,h) are the width and height 1064 of the subrectangle. The client can render the original rectangle by 1065 drawing a filled rectangle of the background pixel value and then 1066 drawing a filled rectangle corresponding to each subrectangle. 1068 On the wire, the data begins with the header: 1070 +---------------+--------------+-------------------------+ 1071 | No. of bytes | Type [Value] | Description | 1072 +---------------+--------------+-------------------------+ 1073 | 4 | U32 | number-of-subrectangles | 1074 | bytesPerPixel | PIXEL | background-pixel-value | 1075 +---------------+--------------+-------------------------+ 1077 This is followed by number-of-subrectangles instances of the 1078 following structure: 1080 +---------------+--------------+---------------------+ 1081 | No. of bytes | Type [Value] | Description | 1082 +---------------+--------------+---------------------+ 1083 | bytesPerPixel | PIXEL | subrect-pixel-value | 1084 | 2 | U16 | x-position | 1085 | 2 | U16 | y-position | 1086 | 2 | U16 | width | 1087 | 2 | U16 | height | 1088 +---------------+--------------+---------------------+ 1090 7.7.4. Hextile Encoding 1092 Note: Hextile encoding is obsolescent. In general, ZRLE and TRLE 1093 encoding are more compact. 1095 Hextile is a variation on RRE. Rectangles are split up into 16x16 1096 tiles, allowing the dimensions of the subrectangles to be specified 1097 in 4 bits each, 16 bits in total. The rectangle is split into tiles 1098 starting at the top left going in left-to-right, top-to-bottom order. 1099 The encoded contents of the tiles simply follow one another in the 1100 predetermined order. If the width of the whole rectangle is not an 1101 exact multiple of 16 then the width of the last tile in each row will 1102 be correspondingly smaller. Similarly if the height of the whole 1103 rectangle is not an exact multiple of 16 then the height of each tile 1104 in the final row will also be smaller. 1106 Each tile is either encoded as raw pixel data, or as a variation on 1107 RRE. Each tile has a background pixel value, as before. The 1108 background pixel value does not need to be explicitly specified for a 1109 given tile if it is the same as the background of the previous tile. 1110 However the background pixel value may not be carried over if the 1111 previous tile was raw. If all of the subrectangles of a tile have 1112 the same pixel value, this can be specified once as a foreground 1113 pixel value for the whole tile. As with the background, the 1114 foreground pixel value can be left unspecified, meaning it is carried 1115 over from the previous tile. The foreground pixel value may not be 1116 carried over if the previous tile was raw or had the SubrectsColored 1117 bit set. It may, however, be carried over from a previous tile with 1118 the AnySubrects bit clear, as long as that tile itself carried over a 1119 valid foreground from its previous tile. 1121 The data consists of each tile encoded in order. Each tile begins 1122 with a subencoding type byte, which is a mask made up of a number of 1123 bits: 1125 +--------------+--------------+---------------------+ 1126 | No. of bytes | Type [Value] | Description | 1127 +--------------+--------------+---------------------+ 1128 | 1 | U8 | subencoding-mask: | 1129 | | [1] | Raw | 1130 | | [2] | BackgroundSpecified | 1131 | | [4] | ForegroundSpecified | 1132 | | [8] | AnySubrects | 1133 | | [16] | SubrectsColored | 1134 +--------------+--------------+---------------------+ 1136 If the Raw bit is set then the other bits are irrelevant; 1137 width*height pixel values follow (where width and height are the 1138 width and height of the tile). Otherwise the other bits in the mask 1139 are as follows: 1141 BackgroundSpecified If set, a pixel value of bytesPerPixel bytes 1142 follows which specifies the background color for this tile. The 1143 first non-raw tile in a rectangle must have this bit set. If this 1144 bit isn't set then the background is the same as the last tile. 1146 ForegroundSpecified If set, a pixel value of bytesPerPixel bytes 1147 follows which specifies the foreground color to be used for all 1148 subrectangles in this tile. 1150 If this bit is set then the SubrectsColored bit must be zero. 1152 AnySubrects If set, a single byte follows giving the number of 1153 subrectangles following. If not set, there are no subrectangles 1154 (i.e. the whole tile is just solid background color). 1156 SubrectsColored If set then each subrectangle is preceded by a pixel 1157 value giving the color of that subrectangle, so a subrectangle is: 1159 +---------------+--------------+---------------------+ 1160 | No. of bytes | Type [Value] | Description | 1161 +---------------+--------------+---------------------+ 1162 | bytesPerPixel | PIXEL | subrect-pixel-value | 1163 | 1 | U8 | x-and-y-position | 1164 | 1 | U8 | width-and-height | 1165 +---------------+--------------+---------------------+ 1167 If not set, all subrectangles are the same color, the foreground 1168 color; if the ForegroundSpecified bit wasn't set then the 1169 foreground is the same as the last tile. A subrectangle is: 1171 +--------------+--------------+------------------+ 1172 | No. of bytes | Type [Value] | Description | 1173 +--------------+--------------+------------------+ 1174 | 1 | U8 | x-and-y-position | 1175 | 1 | U8 | width-and-height | 1176 +--------------+--------------+------------------+ 1178 The position and size of each subrectangle is specified in two bytes, 1179 x-and-y-position and width-and-height. The most-significant four 1180 bits of x-and-y-position specify the X position, the least- 1181 significant specify the Y position. The most-significant four bits 1182 of width-and-height specify the width minus one, the least- 1183 significant specify the height minus one. 1185 7.7.5. TRLE encoding 1187 TRLE stands for Tiled Run-Length Encoding, and combines tiling, 1188 palettisation and run-length encoding. The rectangle is divided into 1189 tiles of 16x16 pixels in left-to-right, top-to-bottom order, similar 1190 to hextile. If the width of the rectangle is not an exact multiple 1191 of 16 then the width of the last tile in each row is smaller, and if 1192 the height of the rectangle is not an exact multiple of 16 then the 1193 height of each tile in the final row is smaller. 1195 TRLE makes use of a new type CPIXEL (compressed pixel). This is the 1196 same as a PIXEL for the agreed pixel format, except as a special 1197 case, it uses a more compact format if true-color-flag is non-zero, 1198 bits-per-pixel is 32, depth is 24 or less and all of the bits making 1199 up the red, green and blue intensities fit in either the least 1200 significant 3 bytes or the most significant 3 bytes. If all of these 1201 are the case, a CPIXEL is only 3 bytes long, and contains the least 1202 significant or the most significant 3 bytes as appropriate. 1203 bytesPerCPixel is the number of bytes in a CPIXEL. 1205 Each tile begins with a subencoding type byte. The top bit of this 1206 byte is set if the tile has been run-length encoded, clear otherwise. 1207 The bottom seven bits indicate the size of the palette used: zero 1208 means no palette, one means that the tile is of a single color, and 2 1209 to 127 indicate a palette of that size. The special subencoding 1210 values 129 and 127 indicate that the palette is to be reused from the 1211 last tile which had a palette, with and without RLE respectively. 1213 Note: in this discussion, the div(a,b) function means the result of 1214 dividing a/b truncated to an integer. 1216 The possible values of subencoding are: 1218 0 Raw pixel data. width*height pixel values follow (where width and 1219 height are the width and height of the tile): 1221 +-----------------------------+--------------+-------------+ 1222 | No. of bytes | Type [Value] | Description | 1223 +-----------------------------+--------------+-------------+ 1224 | width*height*BytesPerCPixel | CPIXEL array | pixels | 1225 +-----------------------------+--------------+-------------+ 1227 1 A solid tile consisting of a single color. The pixel value 1228 follows: 1230 +----------------+--------------+-------------+ 1231 | No. of bytes | Type [Value] | Description | 1232 +----------------+--------------+-------------+ 1233 | bytesPerCPixel | CPIXEL | pixelValue | 1234 +----------------+--------------+-------------+ 1236 2 to 16 Packed palette types. The paletteSize is the value of the 1237 subencoding, which is followed by the palette, consisting of 1238 paletteSize pixel values. The packed pixels follow, with each 1239 pixel represented as a bit field yielding a 0-based index into the 1240 palette. For paletteSize 2, a 1-bit field is used, for 1241 paletteSize 3 or 4 a 2-bit field is used, and for paletteSize from 1242 5 to 16 a 4-bit field is used. The bit fields are packed into 1243 bytes, with the most significant bits representing the leftmost 1244 pixel (i.e. big endian). For tiles not a multiple of 8, 4 or 2 1245 pixels wide (as appropriate), padding bits are used to align each 1246 row to an exact number of bytes. 1248 +----------------------------+--------------+--------------+ 1249 | No. of bytes | Type [Value] | Description | 1250 +----------------------------+--------------+--------------+ 1251 | paletteSize*bytesPerCPixel | CPIXEL array | palette | 1252 | m | U8 array | packedPixels | 1253 +----------------------------+--------------+--------------+ 1255 where m is the number of bytes representing the packed pixels. 1256 For paletteSize of 2 this is div(width+7,8)*height, for 1257 paletteSize of 3 or 4 this is div(width+3,4)*height, or for 1258 paletteSize of 5 to 16 this is div(width+1,2)*height. 1260 17 to 126 Unused. (Packed palettes of these sizes would offer no 1261 advantage over palette RLE). 1263 127 Packed palette with the palette reused from the previous tile. 1264 The subencoding byte is followed by the packed pixels as described 1265 above for packed palette types. 1267 128 Plain RLE. The data consists of a number of runs, repeated 1268 until the tile is done. Runs may continue from the end of one row 1269 to the beginning of the next. Each run is a represented by a 1270 single pixel value followed by the length of the run. The length 1271 is represented as one or more bytes. The length is calculated as 1272 one more than the sum of all the bytes representing the length. 1273 Any byte value other than 255 indicates the final byte. So for 1274 example length 1 is represented as [0], 255 as [254], 256 as 1275 [255,0], 257 as [255,1], 510 as [255,254], 511 as [255,255,0] and 1276 so on. 1278 +-------------------------+--------------+-----------------------+ 1279 | No. of bytes | Type [Value] | Description | 1280 +-------------------------+--------------+-----------------------+ 1281 | bytesPerCPixel | CPIXEL | pixelValue | 1282 | div(runLength - 1, 255) | U8 array | 255 | 1283 | 1 | U8 | (runLength-1) mod 255 | 1284 +-------------------------+--------------+-----------------------+ 1286 129 Palette RLE with the palette reused from the previous tile. 1287 Followed by a number of runs, repeated until the tile is done, as 1288 described below for 130 to 255. 1290 130 to 255 Palette RLE. Followed by the palette, consisting of 1291 paletteSize = (subencoding - 128) pixel values: 1293 +----------------------------+--------------+-------------+ 1294 | No. of bytes | Type [Value] | Description | 1295 +----------------------------+--------------+-------------+ 1296 | paletteSize*bytesPerCPixel | CPIXEL array | palette | 1297 +----------------------------+--------------+-------------+ 1299 Following the palette is, as with plain RLE, of a number of runs, 1300 repeated until the tile is done. A run of length one is 1301 represented simply by a palette index: 1303 +--------------+--------------+--------------+ 1304 | No. of bytes | Type [Value] | Description | 1305 +--------------+--------------+--------------+ 1306 | 1 | U8 | paletteIndex | 1307 +--------------+--------------+--------------+ 1309 A run of length more than one is represented by a palette index 1310 with the top bit set, followed by the length of the run as for 1311 plain RLE. 1313 +-------------------------+--------------+-----------------------+ 1314 | No. of bytes | Type [Value] | Description | 1315 +-------------------------+--------------+-----------------------+ 1316 | 1 | U8 | paletteIndex + 128 | 1317 | div(runLength - 1, 255) | U8 array | 255 | 1318 | 1 | U8 | (runLength-1) mod 255 | 1319 +-------------------------+--------------+-----------------------+ 1321 7.7.6. ZRLE encoding 1323 ZRLE stands for Zlib (see [RFC1950] and [RFC1951]) Run-Length 1324 Encoding, and combines an encoding similar to TRLE with zlib 1325 compression. On the wire, the rectangle begins with a 4-byte length 1326 field, and is followed by that many bytes of zlib-compressed data. A 1327 single zlib "stream" object is used for a given RFB protocol 1328 connection, so that ZRLE rectangles must be encoded and decoded 1329 strictly in order. 1331 +--------------+--------------+-------------+ 1332 | No. of bytes | Type [Value] | Description | 1333 +--------------+--------------+-------------+ 1334 | 4 | U32 | length | 1335 | length | U8 array | zlibData | 1336 +--------------+--------------+-------------+ 1338 The zlibData when uncompressed represents tiles in left-to-right, 1339 top-to-bottom order, similar to TRLE, but with a tile size of 64x64 1340 pixels. If the width of the rectangle is not an exact multiple of 64 1341 then the width of the last tile in each row is smaller, and if the 1342 height of the rectangle is not an exact multiple of 64 then the 1343 height of each tile in the final row is smaller. 1345 The tiles are encoded in exactly the same way as TRLE, except that 1346 subencoding may not take the values 127 or 129, i.e. palettes cannot 1347 be reused between tiles. 1349 The server flushes the zlib stream to a byte boundary at the end of 1350 each ZRLE encoded rectangle. It need not flush the stream between 1351 tiles within a rectangle. Since the zlibData for a single rectangle 1352 can potentially be quite large, clients can incrementally decode and 1353 interpret the zlibData but must not assume that encoded tile data is 1354 byte aligned. 1356 7.8. Pseudo-Encodings 1358 An update rectangle with a "pseudo-encoding" does not directly 1359 represent pixel data but instead allows the server to send arbitrary 1360 data to the client. How this data is interpreted depends on the 1361 pseudo-encoding. 1363 7.8.1. Cursor pseudo-encoding 1365 A client which requests the Cursor pseudo-encoding is declaring that 1366 it is capable of drawing a pointer cursor locally. This can 1367 significantly improve perceived performance over slow links. The 1368 server sets the cursor shape by sending a rectangle with the Cursor 1369 pseudo-encoding as part of an update. The rectangle's x-position and 1370 y-position indicate the hotspot of the cursor, and width and height 1371 indicate the width and height of the cursor in pixels. The data 1372 consists of width*height raw pixel values followed by a shape 1373 bitmask, with one bit corresponding to each pixel in the cursor 1374 rectangle. The bitmask consists of left-to-right, top-to-bottom scan 1375 lines, where each scan line is padded to a whole number of bytes 1376 div(width+7,8). Within each byte the most significant bit represents 1377 the leftmost pixel, with a 1-bit meaning the corresponding pixel in 1378 the cursor is valid. 1380 +----------------------------+--------------+---------------+ 1381 | No. of bytes | Type [Value] | Description | 1382 +----------------------------+--------------+---------------+ 1383 | width*height*bytesPerPixel | PIXEL array | cursor-pixels | 1384 | div(width+7,8)*height | U8 array | bitmask | 1385 +----------------------------+--------------+---------------+ 1387 7.8.2. DesktopSize pseudo-encoding 1389 A client which requests the DesktopSize pseudo-encoding is declaring 1390 that it is capable of coping with a change in the framebuffer width 1391 and height. The server changes the desktop size by sending a 1392 rectangle with the DesktopSize pseudo-encoding as the last rectangle 1393 in an update. The rectangle's x-position and y-position are ignored, 1394 and width and height indicate the new width and height of the 1395 framebuffer. 1397 There is no further data associated with the rectangle. After 1398 changing the desktop size, the server must assume that the client no 1399 longer has the previous framebuffer contents. This will usually 1400 result in a complete update of the framebuffer at the next update. 1401 However for maximum interoperability with existing servers the client 1402 should preserve the top-left portion of the framebuffer between the 1403 old and new sizes. 1405 8. IANA Considerations 1407 IANA has allocated port 5900 to the RFB protocol; the other port 1408 numbers have been used informally and do not match IANA allocations. 1410 8.1. RFB Security Types 1412 8.1.1. Registry Name 1414 The recommended name of this registry is "Remote Framebuffer Security 1415 Types". 1417 8.1.2. Registry Contents 1419 IANA is requested to establish a registry for security types that are 1420 used with the RFB protocol. 1422 The initial entries in the registry are: 1424 +------------+-------------------------+-----------------------+ 1425 | Number | Name | References | 1426 +------------+-------------------------+-----------------------+ 1427 | 0 | Invalid | Reserved | 1428 | 1 | None | (this document) | 1429 | 2 | VNC Authentication | (this document) | 1430 | 3 to 15 | RealVNC | (historic assignment) | 1431 | 16 | Tight | (historic assignment) | 1432 | 17 | Ultra | (historic assignment) | 1433 | 18 | TLS | (historic assignment) | 1434 | 19 | VeNCrypt | (historic assignment) | 1435 | 20 | GTK-VNC SASL | (historic assignment) | 1436 | 21 | MD5 hash authentication | (historic assignment) | 1437 | 22 | Colin Dean xvp | (historic assignment) | 1438 | 128 to 255 | RealVNC | (historic assignment) | 1439 +------------+-------------------------+-----------------------+ 1441 8.2. Client to Server Message Types 1443 8.2.1. Registry Name 1445 The recommended name of this registry is "Remote Framebuffer Client 1446 to Server Message Types". 1448 8.2.2. Registry Contents 1450 IANA is requested to establish a registry for client to server 1451 message types that are used with the RFB protocol. 1453 The initial entries in the registry are: 1455 +--------+------------------------------+-----------------------+ 1456 | Number | Name | References | 1457 +--------+------------------------------+-----------------------+ 1458 | 0 | SetPixelFormat | (this document) | 1459 | 2 | SetEncodings | (this document) | 1460 | 3 | FramebufferUpdateRequest | (this document) | 1461 | 4 | KeyEvent | (this document) | 1462 | 5 | PointerEvent | (this document) | 1463 | 6 | ClientCutText | (this document) | 1464 | 127 | VMWare | (historic assignment) | 1465 | 128 | Nokia Terminal Mode Spec | (historic assignment) | 1466 | 249 | OLIVE Call Control | (historic assignment) | 1467 | 250 | Colin Dean xvp | (historic assignment) | 1468 | 251 | Pierre Ossman SetDesktopSize | (historic assignment) | 1469 | 252 | tight | (historic assignment) | 1470 | 253 | gii | (historic assignment) | 1471 | 254 | VMWare | (historic assignment) | 1472 | 255 | Anthony Liguori | (historic assignment) | 1473 +--------+------------------------------+-----------------------+ 1475 8.3. Server to Client Message Types 1477 8.3.1. Registry Name 1479 The recommended name of this registry is "Remote Framebuffer Server 1480 to Client Message Types". 1482 8.3.2. Registry Contents 1484 IANA is requested to establish a registry for server to client 1485 message types that are used with the RFB protocol. 1487 The initial entries in the registry are: 1489 +--------+--------------------------+-----------------------+ 1490 | Number | Name | References | 1491 +--------+--------------------------+-----------------------+ 1492 | 0 | FramebufferUpdate | (this document) | 1493 | 1 | SetColourMapEntries | (this document) | 1494 | 2 | Bell | (this document) | 1495 | 3 | ServerCutText | (this document) | 1496 | 127 | VMWare | (historic assignment) | 1497 | 128 | Nokia Terminal Mode Spec | (historic assignment) | 1498 | 249 | OLIVE Call Control | (historic assignment) | 1499 | 250 | Colin Dean xvp | (historic assignment) | 1500 | 252 | tight | (historic assignment) | 1501 | 253 | gii | (historic assignment) | 1502 | 254 | VMWare | (historic assignment) | 1503 | 255 | Anthony Liguori | (historic assignment) | 1504 +--------+--------------------------+-----------------------+ 1506 8.4. RFB Encoding Types 1508 8.4.1. Registry Name 1510 The recommended name of this registry is "Remote Framebuffer Encoding 1511 Types". 1513 8.4.2. Registry Contents 1515 IANA is requested to establish a registry for encoding types that are 1516 used with the RFB protocol. 1518 The initial entries in the registry are: 1520 +-------------------+----------------------------+------------------+ 1521 | Number | Name | References | 1522 +-------------------+----------------------------+------------------+ 1523 | 0 | Raw | (this document) | 1524 | 1 | CopyRect | (this document) | 1525 | 2 | RRE | (this document) | 1526 | 5 | Hextile | (this document) | 1527 | 16 | ZRLE | (this document) | 1528 | -239 | Cursor pseudo-encoding | (this document) | 1529 | -223 | DesktopSize | (this document) | 1530 | | pseudo-encoding | | 1531 | 4 | CoRRE | (historic | 1532 | | | assignment) | 1533 | 6 | zlib | (historic | 1534 | | | assignment) | 1535 | 7 | tight | (historic | 1536 | | | assignment) | 1537 | 8 | zlibhex | (historic | 1538 | | | assignment) | 1539 | 15 | TRLE | (this document) | 1540 | 17 | Hitachi ZYWRLE | (historic | 1541 | | | assignment) | 1542 | 1024 to 2047 | RealVNC | (historic | 1543 | | | assignment) | 1544 | -1 to -222 | tight options | (historic | 1545 | | | assignment) | 1546 | -224 to -238 | tight options | (historic | 1547 | | | assignment) | 1548 | -240 to -256 | tight options | (historic | 1549 | | | assignment) | 1550 | -257 to -272 | Anthony Liguori | (historic | 1551 | | | assignment) | 1552 | -273 to -304 | VMWare | (historic | 1553 | | | assignment) | 1554 | -305 | gii | (historic | 1555 | | | assignment) | 1556 | -306 | popa | (historic | 1557 | | | assignment) | 1558 | -307 | Peter Astrand DesktopName | (historic | 1559 | | | assignment) | 1560 | -308 | Pierre Ossman | (historic | 1561 | | ExtendedDesktopSize | assignment) | 1562 | -309 | Colin Dean xvp | (historic | 1563 | | | assignment) | 1564 | -310 | OLIVE Call Control | (historic | 1565 | | | assignment) | 1566 | -412 to -512 | TurboVNC fine-grained | (historic | 1567 | | quality level | assignment) | 1568 | -523 to -524 | Nokia Terminal Mode Spec | (historic | 1569 | | | assignment) | 1570 | -763 to -768 | TurboVNC subsampling level | (historic | 1571 | | | assignment) | 1572 | 0x574d5600 to | VMWare | (historic | 1573 | 0x574d56ff | | assignment) | 1574 +-------------------+----------------------------+------------------+ 1576 9. Security 1578 The RFB protocol as defined here provides no security beyond the 1579 optional and cryptographically weak password check described in 1580 Section 7.2.2. In particular, it provides no protection against 1581 observation of or tampering with the data stream. It has typically 1582 been used on secure physical or virtual networks. 1584 Security methods beyond those described here may be used to protect 1585 the integrity of the data. The client and server might agree to use 1586 an extended security type to encrypt the session, or the session 1587 might be transmitted over a secure channel such as IPSEC [RFC4301] or 1588 SSH [RFC4254]. 1590 10. Acknowledgements 1592 James Weatherall, Andy Harter and Ken Wood also contributed to the 1593 design of the RFB protocol. 1595 RFB and VNC are registered trademarks in the United States and United 1596 Kingdom of RealVNC Limited. 1598 11. References 1600 11.1. References - Normative 1602 [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data Format 1603 Specification version 3.3", RFC 1950, May 1996. 1605 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1606 version 1.3", RFC 1951, May 1996. 1608 [XLIBREF] Nye, A., "XLIB Reference Manual R5", June 1994. 1610 11.2. References - Informative 1612 [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1613 Connection Protocol", RFC 4254, January 2006. 1615 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 1616 Internet Protocol", RFC 4301, December 2005. 1618 Appendix A. Differences in earlier protocol versions 1620 For maximum interoperability, clients and servers should be prepared 1621 to fall back to the earlier 3.3 and 3.7 versions of the RFB protocol. 1622 Any version reported other than 3.7 or 3.8 should be treated as 3.3. 1624 All of the differences occur in the initial handshake phase. Once 1625 the session reaches the ClientInit and ServerInit messages, all three 1626 protocol versions are identical. Even within a protocol version, 1627 clients and servers may support different subsets of the encoding and 1628 pseudo-encoding types. 1630 A.1. Differences in the version 3.3 protocol 1632 The ProtocolVersion message is: 1634 RFB 003.003\n (hex 52 46 42 20 30 30 33 2e 30 30 33 0a) 1636 In the security handshake (Section 7.1.2), rather than a two-way 1637 negotiation the server decides the security type and sends a single 1638 word: 1640 +--------------+--------------+---------------+ 1641 | No. of bytes | Type [Value] | Description | 1642 +--------------+--------------+---------------+ 1643 | 4 | U32 | security-type | 1644 +--------------+--------------+---------------+ 1646 The security-type may only take the value 0, 1 or 2. A value of 0 1647 means that the connection has failed and is followed by a string 1648 giving the reason, as described in Section 7.1.2. 1650 If the security-type is 1, for no authentication, the server does not 1651 send the SecurityResult message but proceeds directly to the 1652 initialization messages. (Section 7.3) 1654 In VNC Authentication (Section 7.2.2), if the authentication fails, 1655 the server sends the SecurityResult message, but does not send an 1656 error message before closing the connection. 1658 A.2. Differences in the version 3.7 protocol 1660 The ProtocolVersion message is: 1662 RFB 003.007\n (hex 52 46 42 20 30 30 33 2e 30 30 37 0a) 1664 After the security handshake, if the security-type is 1, for no 1665 authentication, the server does not send the SecurityResult message 1666 but proceeds directly to the initialization messages. (Section 7.3) 1668 In VNC Authentication (Section 7.2.2), if the authentication fails, 1669 the server sends the SecurityResult message, but does not send an 1670 error message before closing the connection. 1672 Appendix B. Change Log 1674 *NOTE TO RFC EDITOR: This section may be removed upon publication of 1675 this document as an RFC.* 1677 B.1. Changes since -rfb-02 1679 Add length to ZRLE. 1681 Add IANA registries. 1683 Plain protocol used on secure networks. 1685 Use term "client" consistently instead of "viewer". 1687 Clarify reuse of colors between tiles in Hextile and TRLE. 1689 TRLE palette size 127 allowed when RLE used. 1691 B.2. Changes since -rfb-01 1693 Clarify description of TRLE and ZRLE. 1695 Padding should be zero but doesn't matter. 1697 Split normative and informative refs. 1699 B.3. Changes since -rfb-00 1701 Emphasize that the password check is weak. 1703 Add IANA considerations section noting that there aren't any. 1705 Explain how to send Ctrl-Alt-Delete. 1707 Clarify that versions other than 3.3, 3.7, and 3.8 aren't upward 1708 compatible. 1710 Authors' Addresses 1712 Tristan Richardson 1713 RealVNC Ltd. 1714 Betjeman House, 104 Hills Road 1715 Cambridge CB2 1LQ 1716 UK 1718 Phone: +44 1223 310400 1719 Email: standards@realvnc.com 1720 URI: http://www.realvnc.com 1722 John Levine 1723 RealVNC Ltd. 1725 Phone: +44 1223 790005 1726 Email: standards@taugh.com 1727 URI: http://jl.ly