diff options
| author | Thomas Voss <mail@thomasvoss.com> | 2024-11-27 20:54:24 +0100 |
|---|---|---|
| committer | Thomas Voss <mail@thomasvoss.com> | 2024-11-27 20:54:24 +0100 |
| commit | 4bfd864f10b68b71482b35c818559068ef8d5797 (patch) | |
| tree | e3989f47a7994642eb325063d46e8f08ffa681dc /doc/rfc/rfc6143.txt | |
| parent | ea76e11061bda059ae9f9ad130a9895cc85607db (diff) | |
doc: Add RFC documents
Diffstat (limited to 'doc/rfc/rfc6143.txt')
| -rw-r--r-- | doc/rfc/rfc6143.txt | 2187 |
1 files changed, 2187 insertions, 0 deletions
diff --git a/doc/rfc/rfc6143.txt b/doc/rfc/rfc6143.txt new file mode 100644 index 0000000..ff675cb --- /dev/null +++ b/doc/rfc/rfc6143.txt @@ -0,0 +1,2187 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Richardson +Request for Comments: 6143 J. Levine +Category: Informational RealVNC Ltd. +ISSN: 2070-1721 March 2011 + + + The Remote Framebuffer Protocol + +Abstract + + RFB ("remote framebuffer") is a simple protocol for remote access to + graphical user interfaces that allows a client to view and control a + window system on another computer. Because it works at the + framebuffer level, RFB is applicable to all windowing systems and + applications. This document describes the protocol used to + communicate between an RFB client and RFB server. RFB is the + protocol used in VNC. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Not all documents + approved by the IESG are a candidate for any level of Internet + Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6143. + +Copyright Notice + + Copyright (c) 2011 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + +Richardson & Levine Informational [Page 1] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Initial Connection . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Display Protocol . . . . . . . . . . . . . . . . . . . . . . . 4 + 4. Input Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 + 5. Representation of Pixel Data . . . . . . . . . . . . . . . . . 5 + 6. Protocol Versions and Extensions . . . . . . . . . . . . . . . 6 + 7. Protocol Messages . . . . . . . . . . . . . . . . . . . . . . 7 + 7.1. Handshake Messages . . . . . . . . . . . . . . . . . . . . 8 + 7.1.1. ProtocolVersion Handshake . . . . . . . . . . . . . . 8 + 7.1.2. Security Handshake . . . . . . . . . . . . . . . . . . 8 + 7.1.3. SecurityResult Handshake . . . . . . . . . . . . . . . 10 + 7.2. Security Types . . . . . . . . . . . . . . . . . . . . . . 10 + 7.2.1. None . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 7.2.2. VNC Authentication . . . . . . . . . . . . . . . . . . 10 + 7.3. Initialization Messages . . . . . . . . . . . . . . . . . 11 + 7.3.1. ClientInit . . . . . . . . . . . . . . . . . . . . . . 11 + 7.3.2. ServerInit . . . . . . . . . . . . . . . . . . . . . . 11 + 7.4. Pixel Format Data Structure . . . . . . . . . . . . . . . 12 + 7.5. Client-to-Server Messages . . . . . . . . . . . . . . . . 13 + 7.5.1. SetPixelFormat . . . . . . . . . . . . . . . . . . . . 13 + 7.5.2. SetEncodings . . . . . . . . . . . . . . . . . . . . . 14 + 7.5.3. FramebufferUpdateRequest . . . . . . . . . . . . . . . 15 + 7.5.4. KeyEvent . . . . . . . . . . . . . . . . . . . . . . . 16 + 7.5.5. PointerEvent . . . . . . . . . . . . . . . . . . . . . 19 + 7.5.6. ClientCutText . . . . . . . . . . . . . . . . . . . . 19 + 7.6. Server-to-Client Messages . . . . . . . . . . . . . . . . 20 + 7.6.1. FramebufferUpdate . . . . . . . . . . . . . . . . . . 20 + 7.6.2. SetColorMapEntries . . . . . . . . . . . . . . . . . . 21 + 7.6.3. Bell . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 7.6.4. ServerCutText . . . . . . . . . . . . . . . . . . . . 22 + 7.7. Encodings . . . . . . . . . . . . . . . . . . . . . . . . 22 + 7.7.1. Raw Encoding . . . . . . . . . . . . . . . . . . . . . 23 + 7.7.2. CopyRect Encoding . . . . . . . . . . . . . . . . . . 23 + 7.7.3. RRE Encoding . . . . . . . . . . . . . . . . . . . . . 23 + 7.7.4. Hextile Encoding . . . . . . . . . . . . . . . . . . . 24 + 7.7.5. TRLE . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 7.7.6. ZRLE . . . . . . . . . . . . . . . . . . . . . . . . . 30 + 7.8. Pseudo-Encodings . . . . . . . . . . . . . . . . . . . . . 30 + 7.8.1. Cursor Pseudo-Encoding . . . . . . . . . . . . . . . . 30 + 7.8.2. DesktopSize Pseudo-Encoding . . . . . . . . . . . . . 31 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 + 8.1. RFB Security Types . . . . . . . . . . . . . . . . . . . . 32 + 8.1.1. Registry Name . . . . . . . . . . . . . . . . . . . . 32 + 8.1.2. Registry Contents . . . . . . . . . . . . . . . . . . 32 + 8.2. Client-to-Server Message Types . . . . . . . . . . . . . . 32 + 8.2.1. Registry Name . . . . . . . . . . . . . . . . . . . . 32 + + + +Richardson & Levine Informational [Page 2] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + 8.2.2. Registry Contents . . . . . . . . . . . . . . . . . . 32 + 8.3. Server-to-Client Message Types . . . . . . . . . . . . . . 33 + 8.3.1. Registry Name . . . . . . . . . . . . . . . . . . . . 33 + 8.3.2. Registry Contents . . . . . . . . . . . . . . . . . . 33 + 8.4. RFB Encoding Types . . . . . . . . . . . . . . . . . . . . 34 + 8.4.1. Registry Name . . . . . . . . . . . . . . . . . . . . 34 + 8.4.2. Registry Contents . . . . . . . . . . . . . . . . . . 34 + 9. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 36 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 11.1. Normative References . . . . . . . . . . . . . . . . . . . 36 + 11.2. Informative References . . . . . . . . . . . . . . . . . . 36 + Appendix A. Differences in Earlier Protocol Versions . . . . . . 38 + A.1. Differences in the Version 3.3 Protocol . . . . . . . . . 38 + A.2. Differences in the Version 3.7 Protocol . . . . . . . . . 38 + +1. Introduction + + RFB ("remote framebuffer") is a simple protocol for remote access to + graphical user interfaces. Because it works at the framebuffer + level, it is applicable to all windowing systems and applications, + including X11, Windows, and Macintosh. RFB is the protocol used in + VNC. The protocol is widely implemented and has had fairly good + interoperability. + + The remote endpoint where the user sits (typically with a display, + keyboard, and pointer) is called the RFB client or viewer. The + endpoint where changes to the framebuffer originate (i.e., the + windowing system and applications) is known as the RFB server. + + RFB is a "thin client" protocol. The emphasis in the design of the + RFB protocol is to make very few requirements of the client. In this + way, clients can run on the widest range of hardware, and the task of + implementing a client is made as simple as possible. + + The protocol also makes the client stateless. If a client + disconnects from a given server and subsequently reconnects to that + same server, the state of the user interface is preserved. + Furthermore, a different client endpoint can be used to connect to + the same RFB server. At the new endpoint, the user will see exactly + the same graphical user interface as at the original endpoint. In + effect, the interface to the user's applications becomes completely + mobile. Wherever suitable network connectivity exists, the user can + access their own personal applications, and the state of these + applications is preserved between accesses from different locations. + This provides the user with a familiar, uniform view of the computing + infrastructure wherever they go. + + + + +Richardson & Levine Informational [Page 3] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + The RFB protocol has evolved over the past decade, and has been + implemented several times, including at least one open source + version. This document describes the RFB protocol as actually + implemented, so that future implementers can interoperate with + existing clients and servers. + +2. Initial Connection + + An RFB server is typically a long-lived process that maintains the + state of a framebuffer. RFB clients typically connect, communicate + with the server for a period of time to use and manipulate the + framebuffer, then disconnect. A subsequent RFB session will then + pick up where a prior session left off, with the state of the + framebuffer intact. + + An RFB client contacts the server on TCP port 5900. On systems with + multiple RFB servers, server N typically listens on port 5900+N, + analogous to the way that X Window servers listen on port 6000+N. + + Some browser-based clients use a Java application to run the RFB + protocol. RFB servers sometimes provide a simple HTTP server on port + 5800 that provides the requisite Java applet. + + In some cases, the initial roles of the client and server are + reversed, with the RFB client listening on port 5500, and the RFB + server contacting the RFB client. Once the connection is + established, the two sides take their normal roles, with the RFB + server sending the first handshake message. + + Note that the only port number assigned by IANA for RFB is port 5900, + so RFB clients and servers should avoid using other port numbers + unless they are communicating with servers or clients known to use + the non-standard ports. + +3. Display Protocol + + The display side of the protocol is based around a single graphics + primitive: "put a rectangle of pixel data at a given x,y position". + This might seem an inefficient way of drawing many user interface + components. However, allowing various different encodings for the + pixel data gives us a large degree of flexibility in how to trade off + various parameters such as network bandwidth, client drawing speed, + and server processing speed. + + + + + + + + +Richardson & Levine Informational [Page 4] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + A sequence of these rectangles makes a framebuffer update (simply + referred to here as "update"). An update represents a change from + one valid framebuffer state to another, so in some ways is similar to + a frame of video. The rectangles in an update are usually but not + always disjoint. + + The update protocol is demand-driven by the client. That is, an + update is only sent from the server to the client in response to an + explicit request from the client. This gives the protocol an + adaptive quality. The slower the client and the network are, the + lower the rate of updates. With typical applications, changes to the + same area of the framebuffer tend to happen soon after one another. + With a slow client or network, transient states of the framebuffer + can be ignored, resulting in less network traffic and less drawing + for the client. + + After the initial handshake sequence, the protocol is asynchronous, + with each side sending messages as needed. The server must not send + unsolicited updates. An update must only be sent in response to a + request from the client. When several requests from the client are + outstanding, a single update from the server may satisfy all of them. + +4. Input Protocol + + The input side of the protocol is based on a standard workstation + model of a keyboard and multi-button pointing device. Input events + are simply sent to the server by the client whenever the user presses + a key or pointer button, or whenever the pointing device is moved. + These input events can also be synthesized from other non-standard + I/O devices. For example, a pen-based handwriting recognition engine + might generate keyboard events. + +5. Representation of Pixel Data + + Initial interaction between the RFB client and server involves a + negotiation of the format and encoding of the pixel data that will be + sent. This negotiation has been designed to make the job of the + client as easy as possible. The server must always be able to supply + pixel data in the form the client wants. However, if the client is + able to cope equally with several different formats or encodings, it + may choose one that is easier for the server to produce. + + Pixel format refers to the representation of individual colors by + pixel values. The most common pixel formats are 24-bit or 16-bit + "true color", where bit-fields within the pixel value translate + directly to red, green, and blue intensities, and 8-bit "color map" + (palette) where the pixel values are indices into a 256-entry table + that contains the actual RGB intensities. + + + +Richardson & Levine Informational [Page 5] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + Encoding refers to the way that a rectangle of pixel data will be + sent to the client. Every rectangle of pixel data is prefixed by a + header giving the X,Y position of the rectangle on the screen, the + width and height of the rectangle, and an encoding type which + specifies the encoding of the pixel data. The data itself then + follows using the specified encoding. + + The encoding types defined at present are: Raw, CopyRect, RRE, TRLE, + Hextile, and ZRLE. In practice, current servers use the ZRLE, TRLE, + and CopyRect encodings since they provide the best compression for + typical desktops. Clients generally also support Hextile, which was + often used by older RFB servers that didn't support TRLE. See + Section 7.7 for a description of each of the encodings. + +6. Protocol Versions and Extensions + + The RFB protocol has evolved through three published versions: 3.3, + 3.7, and 3.8. This document primarily documents the final version + 3.8; differences from the earlier versions, which are minor, are + described in Appendix A. Under no circumstances should an + implementation use a protocol version number other than one defined + in this document. Over the years, different implementations of RFB + have attempted to use different version numbers to add undocumented + extensions, with the result being that to interoperate, any unknown + 3.x version must be treated as 3.3, so it is not possible to add a + 3.9 or higher version in a backward-compatible fashion. Future + evolution of RFB will use 4.x version numbers. + + It is not necessary to change the protocol version number to extend + the protocol. The protocol can be extended within an existing + version by: + + New encodings + A new encoding type can be added to the protocol relatively easily + while maintaining compatibility with existing clients and servers. + Existing servers will simply ignore requests for a new encoding + that they don't support. Existing clients will never request the + new encoding so will never see rectangles encoded that way. + + Pseudo-encodings + In addition to genuine encodings, a client can request a "pseudo- + encoding" to declare to the server that it supports a certain + extension to the protocol. A server that does not support the + extension will simply ignore the pseudo-encoding. Note that this + means the client must assume that the server does not support the + extension until it gets some extension-specific confirmation from + the server. See Section 7.8 for a description of current pseudo- + encodings. + + + +Richardson & Levine Informational [Page 6] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + New security types + Adding a new security type gives full flexibility in modifying the + behavior of the protocol without sacrificing compatibility with + existing clients and servers. A client and server that agree on a + new security type can effectively talk whatever protocol they like + after that -- it doesn't necessarily have to be anything like the + RFB protocol. + + See Section 8 for information on obtaining an ID for a new encoding + or security type. + +7. Protocol Messages + + The RFB protocol can operate over any reliable transport, either + byte-stream or message based. It usually operates over a TCP/IP + connection. There are three stages to the protocol. First is the + handshaking phase, the purpose of which is to agree upon the protocol + version and the type of security to be used. The second stage is an + initialization phase where the client and server exchange ClientInit + and ServerInit messages. The final stage is the normal protocol + interaction. The client can send whichever messages it wants, and + may receive messages from the server as a result. All these messages + begin with a message-type byte, followed by message-specific data. + + The following descriptions of protocol messages use the basic types + U8, U16, U32, S8, S16, and S32. These represent, respectively, 8-, + 16-, and 32-bit unsigned integers and 8-, 16-, and 32-bit signed + integers. All multiple-byte integers (other than pixel values + themselves) are in big endian order (most significant byte first). + Some messages use arrays of the basic types, with the number of + entries in the array determined from fields preceding the array. + + The type PIXEL means a pixel value of bytesPerPixel bytes, where + bytesPerPixel is the number of bits-per-pixel divided by 8. The + bits-per-pixel is agreed by the client and server, either in the + ServerInit message (Section 7.3.2) or a SetPixelFormat message + (Section 7.5.1). See Section 7.4 for the detailed description of the + pixel format. + + Several message formats include padding bits or bytes. For maximum + compatibility, messages should be generated with padding set to zero, + but message recipients should not assume padding has any particular + value. + + + + + + + + +Richardson & Levine Informational [Page 7] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.1. Handshake Messages + + When an RFB client and server first connect, they exchange a sequence + of handshake messages that determine the protocol version, what type + of connection security (if any) to use, a password check if the + security type requires it, and some initialization information. + +7.1.1. ProtocolVersion Handshake + + Handshaking begins by the server sending the client a ProtocolVersion + message. This lets the client know which is the highest RFB protocol + version number supported by the server. The client then replies with + a similar message giving the version number of the protocol that + should actually be used (which may be different to that quoted by the + server). A client should never request a protocol version higher + than that offered by the server. It is intended that both clients + and servers may provide some level of backwards compatibility by this + mechanism. + + The only published protocol versions at this time are 3.3, 3.7, and + 3.8. Other version numbers are reported by some servers and clients, + but should be interpreted as 3.3 since they do not implement the + different handshake in 3.7 or 3.8. Addition of a new encoding or + pseudo-encoding type does not require a change in protocol version, + since a server can simply ignore encodings it does not understand. + + The ProtocolVersion message consists of 12 bytes interpreted as a + string of ASCII characters in the format "RFB xxx.yyy\n" where xxx + and yyy are the major and minor version numbers, left-padded with + zeros: + + RFB 003.008\n (hex 52 46 42 20 30 30 33 2e 30 30 38 0a) + +7.1.2. Security Handshake + + Once the protocol version has been decided, the server and client + must agree on the type of security to be used on the connection. The + server lists the security types that it supports: + + +--------------------------+-------------+--------------------------+ + | No. of bytes | Type | Description | + | | [Value] | | + +--------------------------+-------------+--------------------------+ + | 1 | U8 | number-of-security-types | + | number-of-security-types | U8 array | security-types | + +--------------------------+-------------+--------------------------+ + + + + + +Richardson & Levine Informational [Page 8] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + If the server listed at least one valid security type supported by + the client, the client sends back a single byte indicating which + security type is to be used on the connection: + + +--------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+---------------+ + | 1 | U8 | security-type | + +--------------+--------------+---------------+ + + If number-of-security-types is zero, then for some reason the + connection failed (e.g., the server cannot support the desired + protocol version). This is followed by a string describing the + reason (where a string is specified as a length followed by that many + ASCII characters): + + +---------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +---------------+--------------+---------------+ + | 4 | U32 | reason-length | + | reason-length | U8 array | reason-string | + +---------------+--------------+---------------+ + + The server closes the connection after sending the reason-string. + + The security types defined in this document are: + + +--------+--------------------+ + | Number | Name | + +--------+--------------------+ + | 0 | Invalid | + | 1 | None | + | 2 | VNC Authentication | + +--------+--------------------+ + + Other security types exist but are not publicly documented. + + Once the security-type has been decided, data specific to that + security-type follows (see Section 7.2 for details). At the end of + the security handshaking phase, the protocol normally continues with + the SecurityResult message. + + Note that after the security handshaking phase, it is possible that + further communication is over an encrypted or otherwise altered + channel if the two ends agree on an extended security type beyond the + ones described here. + + + + + +Richardson & Levine Informational [Page 9] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.1.3. SecurityResult Handshake + + The server sends a word to inform the client whether the security + handshaking was successful. + + +--------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------+ + | 4 | U32 | status: | + | | 0 | OK | + | | 1 | failed | + +--------------+--------------+-------------+ + + If successful, the protocol passes to the initialization phase + (Section 7.3). + + If unsuccessful, the server sends a string describing the reason for + the failure, and then closes the connection: + + +---------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +---------------+--------------+---------------+ + | 4 | U32 | reason-length | + | reason-length | U8 array | reason-string | + +---------------+--------------+---------------+ + +7.2. Security Types + + Two security types are defined here. + +7.2.1. None + + No authentication is needed. The protocol continues with the + SecurityResult message. + +7.2.2. VNC Authentication + + VNC authentication is to be used. The server sends a random 16-byte + challenge: + + +--------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------+ + | 16 | U8 | challenge | + +--------------+--------------+-------------+ + + + + + + +Richardson & Levine Informational [Page 10] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + The client encrypts the challenge with DES, using a password supplied + by the user as the key. To form the key, the password is truncated + to eight characters, or padded with null bytes on the right. The + client then sends the resulting 16-byte response: + + +--------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------+ + | 16 | U8 | response | + +--------------+--------------+-------------+ + + The protocol continues with the SecurityResult message. + + This type of authentication is known to be cryptographically weak and + is not intended for use on untrusted networks. Many implementations + will want to use stronger security, such as running the session over + an encrypted channel provided by IPsec [RFC4301] or SSH [RFC4254]. + +7.3. Initialization Messages + + Once the client and server agree on and perhaps validate a security + type, the protocol passes to the initialization stage. The client + sends a ClientInit message. Then, the server sends a ServerInit + message. + +7.3.1. ClientInit + + +--------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------+ + | 1 | U8 | shared-flag | + +--------------+--------------+-------------+ + + Shared-flag is non-zero (true) if the server should try to share the + desktop by leaving other clients connected, and zero (false) if it + should give exclusive access to this client by disconnecting all + other clients. + +7.3.2. ServerInit + + After receiving the ClientInit message, the server sends a ServerInit + message. This tells the client the width and height of the server's + framebuffer, its pixel format, and the name associated with the + desktop: + + + + + + + +Richardson & Levine Informational [Page 11] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + +--------------+--------------+------------------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+------------------------------+ + | 2 | U16 | framebuffer-width in pixels | + | 2 | U16 | framebuffer-height in pixels | + | 16 | PIXEL_FORMAT | server-pixel-format | + | 4 | U32 | name-length | + | name-length | U8 array | name-string | + +--------------+--------------+------------------------------+ + + Server-pixel-format specifies the server's natural pixel format. + This pixel format will be used unless the client requests a different + format using the SetPixelFormat message (Section 7.5.1). + +7.4. Pixel Format Data Structure + + Several server-to-client messages include a PIXEL_FORMAT, a 16-byte + structure that describes the way a pixel is transmitted. + + +--------------+--------------+-----------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-----------------+ + | 1 | U8 | bits-per-pixel | + | 1 | U8 | depth | + | 1 | U8 | big-endian-flag | + | 1 | U8 | true-color-flag | + | 2 | U16 | red-max | + | 2 | U16 | green-max | + | 2 | U16 | blue-max | + | 1 | U8 | red-shift | + | 1 | U8 | green-shift | + | 1 | U8 | blue-shift | + | 3 | | padding | + +--------------+--------------+-----------------+ + + Bits-per-pixel is the number of bits used for each pixel value on the + wire. This must be greater than or equal to the depth, which is the + number of useful bits in the pixel value. Currently bits-per-pixel + must be 8, 16, or 32. Big-endian-flag is non-zero (true) if multi- + byte pixels are interpreted as big endian. Although the depth should + be consistent with the bits-per-pixel and the various -max values, + clients do not use it when interpreting pixel data. + + If true-color-flag is non-zero (true), then the last six items + specify how to extract the red, green, and blue intensities from the + pixel value. Red-max is the maximum red value and must be 2^N - 1, + where N is the number of bits used for red. Note the -max values are + always in big endian order. Red-shift is the number of shifts needed + + + +Richardson & Levine Informational [Page 12] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + to get the red value in a pixel to the least significant bit. Green- + max, green-shift, blue-max, and blue-shift are similar for green and + blue. For example, to find the red value (between 0 and red-max) + from a given pixel, do the following: + + o Swap the pixel value according to big-endian-flag, e.g., if big- + endian-flag is zero (false) and host byte order is big endian, + then swap. + + o Shift right by red-shift. + + o AND with red-max (in host byte order). + + If true-color-flag is zero (false), then the server uses pixel values + that are not directly composed from the red, green, and blue + intensities, but serve as indices into a color map. Entries in the + color map are set by the server using the SetColorMapEntries message + (See Section 7.6.2). + +7.5. Client-to-Server Messages + + The client-to-server message types defined in this document are: + + +--------+--------------------------+ + | Number | Name | + +--------+--------------------------+ + | 0 | SetPixelFormat | + | 2 | SetEncodings | + | 3 | FramebufferUpdateRequest | + | 4 | KeyEvent | + | 5 | PointerEvent | + | 6 | ClientCutText | + +--------+--------------------------+ + + Other message types exist but are not publicly documented. Before + sending a message other than those described in this document, a + client must have determined that the server supports the relevant + extension by receiving an appropriate extension-specific confirmation + from the server. + +7.5.1. SetPixelFormat + + A SetPixelFormat message sets the format in which pixel values should + be sent in FramebufferUpdate messages. If the client does not send a + SetPixelFormat message, then the server sends pixel values in its + natural format as specified in the ServerInit message + (Section 7.3.2). + + + + +Richardson & Levine Informational [Page 13] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + If true-color-flag is zero (false), then this indicates that a "color + map" is to be used. The server can set any of the entries in the + color map using the SetColorMapEntries message (Section 7.6.2). + Immediately after the client has sent this message, the contents of + the color map are undefined, even if entries had previously been set + by the server. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [0] | message-type | + | 3 | | padding | + | 16 | PIXEL_FORMAT | pixel-format | + +--------------+--------------+--------------+ + + PIXEL_FORMAT is as described in Section 7.4. + +7.5.2. SetEncodings + + A SetEncodings message sets the encoding types in which pixel data + can be sent by the server. The order of the encoding types given in + this message is a hint by the client as to its preference (the first + encoding specified being most preferred). The server may or may not + choose to make use of this hint. Pixel data may always be sent in + raw encoding even if not specified explicitly here. + + In addition to genuine encodings, a client can request "pseudo- + encodings" to declare to the server that it supports certain + extensions to the protocol. A server that does not support the + extension will simply ignore the pseudo-encoding. Note that this + means the client must assume that the server does not support the + extension until it gets some extension-specific confirmation from the + server. + + See Section 7.7 for a description of each encoding and Section 7.8 + for the meaning of pseudo-encodings. + + +--------------+--------------+---------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+---------------------+ + | 1 | U8 [2] | message-type | + | 1 | | padding | + | 2 | U16 | number-of-encodings | + +--------------+--------------+---------------------+ + + + + + + + +Richardson & Levine Informational [Page 14] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + This is followed by number-of-encodings repetitions of the following: + + +--------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+---------------+ + | 4 | S32 | encoding-type | + +--------------+--------------+---------------+ + +7.5.3. FramebufferUpdateRequest + + A FramebufferUpdateRequest message notifies the server that the + client is interested in the area of the framebuffer specified by + x-position, y-position, width, and height. The server usually + responds to a FramebufferUpdateRequest by sending a + FramebufferUpdate. A single FramebufferUpdate may be sent in reply + to several FramebufferUpdateRequests. + + The server assumes that the client keeps a copy of all parts of the + framebuffer in which it is interested. This means that normally the + server only needs to send incremental updates to the client. + + If the client has lost the contents of a particular area that it + needs, then the client sends a FramebufferUpdateRequest with + incremental set to zero (false). This requests that the server send + the entire contents of the specified area as soon as possible. The + area will not be updated using the CopyRect encoding. + + If the client has not lost any contents of the area in which it is + interested, then it sends a FramebufferUpdateRequest with incremental + set to non-zero (true). If and when there are changes to the + specified area of the framebuffer, the server will send a + FramebufferUpdate. Note that there may be an indefinite period + between the FramebufferUpdateRequest and the FramebufferUpdate. + + In the case of a fast client, the client may want to regulate the + rate at which it sends incremental FramebufferUpdateRequests to avoid + excessive network traffic. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [3] | message-type | + | 1 | U8 | incremental | + | 2 | U16 | x-position | + | 2 | U16 | y-position | + | 2 | U16 | width | + | 2 | U16 | height | + +--------------+--------------+--------------+ + + + +Richardson & Levine Informational [Page 15] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.5.4. KeyEvent + + A KeyEvent message indicates a key press or release. Down-flag is + non-zero (true) if the key is now pressed, and zero (false) if it is + now released. The key itself is specified using the "keysym" values + defined by the X Window System, even if the client or server is not + running the X Window System. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [4] | message-type | + | 1 | U8 | down-flag | + | 2 | | padding | + | 4 | U32 | key | + +--------------+--------------+--------------+ + + For most ordinary keys, the keysym is the same as the corresponding + ASCII value. For full details, see [XLIBREF] or see the header file + <X11/keysymdef.h> in the X Window System distribution. Some other + common keys are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Richardson & Levine Informational [Page 16] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + +-----------------+--------------------+ + | Key name | Keysym value (hex) | + +-----------------+--------------------+ + | BackSpace | 0xff08 | + | Tab | 0xff09 | + | Return or Enter | 0xff0d | + | Escape | 0xff1b | + | Insert | 0xff63 | + | Delete | 0xffff | + | Home | 0xff50 | + | End | 0xff57 | + | Page Up | 0xff55 | + | Page Down | 0xff56 | + | Left | 0xff51 | + | Up | 0xff52 | + | Right | 0xff53 | + | Down | 0xff54 | + | F1 | 0xffbe | + | F2 | 0xffbf | + | F3 | 0xffc0 | + | F4 | 0xffc1 | + | ... | ... | + | F12 | 0xffc9 | + | Shift (left) | 0xffe1 | + | Shift (right) | 0xffe2 | + | Control (left) | 0xffe3 | + | Control (right) | 0xffe4 | + | Meta (left) | 0xffe7 | + | Meta (right) | 0xffe8 | + | Alt (left) | 0xffe9 | + | Alt (right) | 0xffea | + +-----------------+--------------------+ + + The interpretation of keysyms is a complex area. In order to be as + widely interoperable as possible, the following guidelines should be + followed: + + o The "shift state" (i.e., whether either of the Shift keysyms is + down) should only be used as a hint when interpreting a keysym. + For example, on a US keyboard the '#' character is shifted, but on + a UK keyboard it is not. A server with a US keyboard receiving a + '#' character from a client with a UK keyboard will not have been + sent any shift presses. In this case, it is likely that the + server will internally need to simulate a shift press on its local + system in order to get a '#' character and not a '3'. + + + + + + +Richardson & Levine Informational [Page 17] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + o The difference between upper and lower case keysyms is + significant. This is unlike some of the keyboard processing in + the X Window System that treats them as the same. For example, a + server receiving an upper case 'A' keysym without any shift + presses should interpret it as an upper case 'A'. Again this may + involve an internal simulated shift press. + + o Servers should ignore "lock" keysyms such as CapsLock and NumLock + where possible. Instead, they should interpret each character- + based keysym according to its case. + + o Unlike Shift, the state of modifier keys such as Control and Alt + should be taken as modifying the interpretation of other keysyms. + Note that there are no keysyms for ASCII control characters such + as Ctrl-A -- these should be generated by clients sending a + Control press followed by an 'a' press. + + o On a client where modifiers like Control and Alt can also be used + to generate character-based keysyms, the client may need to send + extra "release" events in order that the keysym is interpreted + correctly. For example, on a German PC keyboard, Ctrl-Alt-Q + generates the '@' character. In this case, the client needs to + send simulated release events for Control and Alt in order that + the '@' character is interpreted correctly, since Ctrl-Alt-@ may + mean something completely different to the server. + + o There is no universal standard for "backward tab" in the X Window + System. On some systems shift+tab gives the keysym + "ISO_Left_Tab", on others it gives a private "BackTab" keysym, and + on others it gives "Tab" and applications tell from the shift + state that it means backward-tab rather than forward-tab. In the + RFB protocol, the latter approach is preferred. Clients should + generate a shifted Tab rather than ISO_Left_Tab. However, to be + backwards-compatible with existing clients, servers should also + recognize ISO_Left_Tab as meaning a shifted Tab. + + o Modern versions of the X Window System handle keysyms for Unicode + characters, consisting of the Unicode character with the hex + 1000000 bit set. For maximum compatibility, if a key has both a + Unicode and a legacy encoding, clients should send the legacy + encoding. + + o Some systems give a special interpretation to key combinations + such as Ctrl-Alt-Delete. RFB clients typically provide a menu or + toolbar function to send such key combinations. The RFB protocol + does not treat them specially; to send Ctrl-Alt-Delete, the client + sends the key presses for left or right Control, left or right + + + + +Richardson & Levine Informational [Page 18] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + Alt, and Delete, followed by the key releases. Many RFB servers + accept Shift-Ctrl-Alt-Delete as a synonym for Ctrl-Alt-Delete that + can be entered directly from the keyboard. + +7.5.5. PointerEvent + + A PointerEvent message indicates either pointer movement or a pointer + button press or release. The pointer is now at (x-position, + y-position), and the current state of buttons 1 to 8 are represented + by bits 0 to 7 of button-mask, respectively; 0 means up, 1 means down + (pressed). + + On a conventional mouse, buttons 1, 2, and 3 correspond to the left, + middle, and right buttons on the mouse. On a wheel mouse, each step + of the wheel upwards is represented by a press and release of button + 4, and each step downwards is represented by a press and release of + button 5. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [5] | message-type | + | 1 | U8 | button-mask | + | 2 | U16 | x-position | + | 2 | U16 | y-position | + +--------------+--------------+--------------+ + +7.5.6. ClientCutText + + RFB provides limited support for synchronizing the "cut buffer" of + selected text between client and server. This message tells the + server that the client has new ISO 8859-1 (Latin-1) text in its cut + buffer. Ends of lines are represented by the newline character (hex + 0a) alone. No carriage-return (hex 0d) is used. There is no way to + transfer text outside the Latin-1 character set. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [6] | message-type | + | 3 | | padding | + | 4 | U32 | length | + | length | U8 array | text | + +--------------+--------------+--------------+ + + + + + + + +Richardson & Levine Informational [Page 19] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.6. Server-to-Client Messages + + The server-to-client message types defined in this document are: + + +--------+--------------------+ + | Number | Name | + +--------+--------------------+ + | 0 | FramebufferUpdate | + | 1 | SetColorMapEntries | + | 2 | Bell | + | 3 | ServerCutText | + +--------+--------------------+ + + Other private message types exist but are not publicly documented. + Before sending a message other than those described in this document + a server must have determined that the client supports the relevant + extension by receiving some extension-specific confirmation from the + client -- usually a request for a given pseudo-encoding. + +7.6.1. FramebufferUpdate + + A framebuffer update consists of a sequence of rectangles of pixel + data that the client should put into its framebuffer. It is sent in + response to a FramebufferUpdateRequest from the client. Note that + there may be an indefinite period between the + FramebufferUpdateRequest and the FramebufferUpdate. + + +--------------+--------------+----------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+----------------------+ + | 1 | U8 [0] | message-type | + | 1 | | padding | + | 2 | U16 | number-of-rectangles | + +--------------+--------------+----------------------+ + + This header is followed by number-of-rectangles rectangles of pixel + data. Each rectangle starts with a rectangle header: + + +--------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+---------------+ + | 2 | U16 | x-position | + | 2 | U16 | y-position | + | 2 | U16 | width | + | 2 | U16 | height | + | 4 | S32 | encoding-type | + +--------------+--------------+---------------+ + + + + +Richardson & Levine Informational [Page 20] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + The rectangle header is followed by the pixel data in the specified + encoding. See Section 7.7 for the format of the data for each + encoding and Section 7.8 for the meaning of pseudo-encodings. + +7.6.2. SetColorMapEntries + + When the pixel format uses a "color map", this message tells the + client that the specified pixel values should be mapped to the given + RGB values. Note that this message may only update part of the color + map. This message should not be sent by the server until after the + client has sent at least one FramebufferUpdateRequest, and only when + the agreed pixel format uses a color map. + + Color map values are always 16 bits, with the range of values running + from 0 to 65535, regardless of the display hardware in use. The + color map value for white, for example, is 65535,65535,65535. + + The message starts with a header describing the range of colormap + entries to be updated. + + +--------------+--------------+------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+------------------+ + | 1 | U8 [1] | message-type | + | 1 | | padding | + | 2 | U16 | first-color | + | 2 | U16 | number-of-colors | + +--------------+--------------+------------------+ + + This header is followed by number-of-colors RGB values, each of which + is in this format: + + +--------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------+ + | 2 | U16 | red | + | 2 | U16 | green | + | 2 | U16 | blue | + +--------------+--------------+-------------+ + + + + + + + + + + + + +Richardson & Levine Informational [Page 21] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.6.3. Bell + + A Bell message makes an audible signal on the client if it provides + one. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [2] | message-type | + +--------------+--------------+--------------+ + +7.6.4. ServerCutText + + The server has new ISO 8859-1 (Latin-1) text in its cut buffer. Ends + of lines are represented by the newline character (hex 0a) alone. No + carriage-return (hex 0d) is used. There is no way to transfer text + outside the Latin-1 character set. + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 [3] | message-type | + | 3 | | padding | + | 4 | U32 | length | + | length | U8 array | text | + +--------------+--------------+--------------+ + +7.7. Encodings + + The encodings defined in this document are: + + +--------+-----------------------------+ + | Number | Name | + +--------+-----------------------------+ + | 0 | Raw | + | 1 | CopyRect | + | 2 | RRE | + | 5 | Hextile | + | 15 | TRLE | + | 16 | ZRLE | + | -239 | Cursor pseudo-encoding | + | -223 | DesktopSize pseudo-encoding | + +--------+-----------------------------+ + + Other encoding types exist but are not publicly documented. + + + + + + +Richardson & Levine Informational [Page 22] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.7.1. Raw Encoding + + The simplest encoding type is raw pixel data. In this case, the data + consists of width*height pixel values (where width and height are the + width and height of the rectangle). The values simply represent each + pixel in left-to-right scan line order. All RFB clients must be able + to handle pixel data in this raw encoding, and RFB servers should + only produce raw encoding unless the client specifically asks for + some other encoding type. + + +----------------------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +----------------------------+--------------+-------------+ + | width*height*bytesPerPixel | PIXEL array | pixels | + +----------------------------+--------------+-------------+ + +7.7.2. CopyRect Encoding + + The CopyRect (copy rectangle) encoding is a very simple and efficient + encoding that can be used when the client already has the same pixel + data elsewhere in its framebuffer. The encoding on the wire simply + consists of an X,Y coordinate. This gives a position in the + framebuffer from which the client can copy the rectangle of pixel + data. This can be used in a variety of situations, the most common + of which are when the user moves a window across the screen, and when + the contents of a window are scrolled. + + +--------------+--------------+----------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+----------------+ + | 2 | U16 | src-x-position | + | 2 | U16 | src-y-position | + +--------------+--------------+----------------+ + + For maximum compatibility, the source rectangle of a CopyRect should + not include pixels updated by previous entries in the same + FramebufferUpdate message. + +7.7.3. RRE Encoding + + Note: RRE encoding is obsolescent. In general, ZRLE and TRLE + encodings are more compact. + + RRE stands for rise-and-run-length encoding. As its name implies, it + is essentially a two-dimensional analogue of run-length encoding. + RRE-encoded rectangles arrive at the client in a form that can be + + + + + +Richardson & Levine Informational [Page 23] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + rendered immediately by the simplest of graphics engines. RRE is not + appropriate for complex desktops, but can be useful in some + situations. + + The basic idea behind RRE is the partitioning of a rectangle of pixel + data into rectangular subregions (subrectangles) each of which + consists of pixels of a single value, and the union of which + comprises the original rectangular region. The near-optimal + partition of a given rectangle into such subrectangles is relatively + easy to compute. + + The encoding consists of a background pixel value, Vb (typically the + most prevalent pixel value in the rectangle) and a count N, followed + by a list of N subrectangles, each of which consists of a tuple + <v,x,y,w,h> where v (which should be different from Vb) is the pixel + value, (x,y) are the coordinates of the subrectangle relative to the + top-left corner of the rectangle, and (w,h) are the width and height + of the subrectangle. The client can render the original rectangle by + drawing a filled rectangle of the background pixel value and then + drawing a filled rectangle corresponding to each subrectangle. + + On the wire, the data begins with the header: + + +---------------+--------------+-------------------------+ + | No. of bytes | Type [Value] | Description | + +---------------+--------------+-------------------------+ + | 4 | U32 | number-of-subrectangles | + | bytesPerPixel | PIXEL | background-pixel-value | + +---------------+--------------+-------------------------+ + + This is followed by number-of-subrectangles instances of the + following structure: + + +---------------+--------------+---------------------+ + | No. of bytes | Type [Value] | Description | + +---------------+--------------+---------------------+ + | bytesPerPixel | PIXEL | subrect-pixel-value | + | 2 | U16 | x-position | + | 2 | U16 | y-position | + | 2 | U16 | width | + | 2 | U16 | height | + +---------------+--------------+---------------------+ + +7.7.4. Hextile Encoding + + Note: Hextile encoding is obsolescent. In general, ZRLE and TRLE + encodings are more compact. + + + + +Richardson & Levine Informational [Page 24] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + Hextile is a variation on RRE. Rectangles are split up into 16x16 + tiles, allowing the dimensions of the subrectangles to be specified + in 4 bits each, 16 bits in total. The rectangle is split into tiles + starting at the top left going in left-to-right, top-to-bottom order. + The encoded contents of the tiles simply follow one another in the + predetermined order. If the width of the whole rectangle is not an + exact multiple of 16, then the width of the last tile in each row + will be correspondingly smaller. Similarly, if the height of the + whole rectangle is not an exact multiple of 16, then the height of + each tile in the final row will also be smaller. + + Each tile is either encoded as raw pixel data, or as a variation on + RRE. Each tile has a background pixel value, as before. The + background pixel value does not need to be explicitly specified for a + given tile if it is the same as the background of the previous tile. + However, the background pixel value may not be carried over if the + previous tile was raw. If all of the subrectangles of a tile have + the same pixel value, this can be specified once as a foreground + pixel value for the whole tile. As with the background, the + foreground pixel value can be left unspecified, meaning it is carried + over from the previous tile. The foreground pixel value may not be + carried over if the previous tile was raw or had the SubrectsColored + bit set. It may, however, be carried over from a previous tile with + the AnySubrects bit clear, as long as that tile itself carried over a + valid foreground from its previous tile. + + The data consists of each tile encoded in order. Each tile begins + with a subencoding type byte, which is a mask made up of a number of + bits: + + +--------------+--------------+---------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+---------------------+ + | 1 | U8 | subencoding-mask: | + | | [1] | Raw | + | | [2] | BackgroundSpecified | + | | [4] | ForegroundSpecified | + | | [8] | AnySubrects | + | | [16] | SubrectsColored | + +--------------+--------------+---------------------+ + + If the Raw bit is set, then the other bits are irrelevant; + width*height pixel values follow (where width and height are the + width and height of the tile). Otherwise, the other bits in the mask + are as follows: + + + + + + +Richardson & Levine Informational [Page 25] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + BackgroundSpecified + If set, a pixel value of bytesPerPixel bytes follows and specifies + the background color for this tile. The first non-raw tile in a + rectangle must have this bit set. If this bit isn't set, then the + background is the same as the last tile. + + ForegroundSpecified + If set, a pixel value of bytesPerPixel bytes follows and specifies + the foreground color to be used for all subrectangles in this + tile. + + If this bit is set, then the SubrectsColored bit must be zero. + + AnySubrects + If set, a single byte follows and gives the number of + subrectangles following. If not set, there are no subrectangles + (i.e., the whole tile is just solid background color). + + SubrectsColored + If set, then each subrectangle is preceded by a pixel value giving + the color of that subrectangle, so a subrectangle is: + + +---------------+--------------+---------------------+ + | No. of bytes | Type [Value] | Description | + +---------------+--------------+---------------------+ + | bytesPerPixel | PIXEL | subrect-pixel-value | + | 1 | U8 | x-and-y-position | + | 1 | U8 | width-and-height | + +---------------+--------------+---------------------+ + + If not set, all subrectangles are the same color -- the foreground + color; if the ForegroundSpecified bit wasn't set, then the + foreground is the same as the last tile. A subrectangle is: + + +--------------+--------------+------------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+------------------+ + | 1 | U8 | x-and-y-position | + | 1 | U8 | width-and-height | + +--------------+--------------+------------------+ + + The position and size of each subrectangle is specified in two bytes, + x-and-y-position and width-and-height. The most significant 4 bits + of x-and-y-position specify the X position, the least significant + specify the Y position. The most significant 4 bits of width-and- + height specify the width minus 1, the least significant specify the + height minus 1. + + + + +Richardson & Levine Informational [Page 26] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.7.5. TRLE + + TRLE stands for Tiled Run-Length Encoding, and combines tiling, + palettization, and run-length encoding. The rectangle is divided + into tiles of 16x16 pixels in left-to-right, top-to-bottom order, + similar to Hextile. If the width of the rectangle is not an exact + multiple of 16, then the width of the last tile in each row is + smaller, and if the height of the rectangle is not an exact multiple + of 16, then the height of each tile in the final row is smaller. + + TRLE makes use of a new type CPIXEL (compressed pixel). This is the + same as a PIXEL for the agreed pixel format, except as a special + case, it uses a more compact format if true-color-flag is non-zero, + bits-per-pixel is 32, depth is 24 or less, and all of the bits making + up the red, green, and blue intensities fit in either the least + significant 3 bytes or the most significant 3 bytes. If all of these + are the case, a CPIXEL is only 3 bytes long, and contains the least + significant or the most significant 3 bytes as appropriate. + bytesPerCPixel is the number of bytes in a CPIXEL. + + Each tile begins with a subencoding type byte. The top bit of this + byte is set if the tile has been run-length encoded, clear otherwise. + The bottom 7 bits indicate the size of the palette used: zero means + no palette, 1 means that the tile is of a single color, and 2 to 127 + indicate a palette of that size. The special subencoding values 129 + and 127 indicate that the palette is to be reused from the last tile + that had a palette, with and without RLE, respectively. + + Note: in this discussion, the div(a,b) function means the result of + dividing a/b truncated to an integer. + + The possible values of subencoding are: + + 0: Raw pixel data. width*height pixel values follow (where width and + height are the width and height of the tile): + + +-----------------------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +-----------------------------+--------------+-------------+ + | width*height*BytesPerCPixel | CPIXEL array | pixels | + +-----------------------------+--------------+-------------+ + + + + + + + + + + +Richardson & Levine Informational [Page 27] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + 1: A solid tile consisting of a single color. The pixel value + follows: + + +----------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +----------------+--------------+-------------+ + | bytesPerCPixel | CPIXEL | pixelValue | + +----------------+--------------+-------------+ + + 2 to 16: Packed palette types. The paletteSize is the value of the + subencoding, which is followed by the palette, consisting of + paletteSize pixel values. The packed pixels follow, with each + pixel represented as a bit field yielding a zero-based index into + the palette. For paletteSize 2, a 1-bit field is used; for + paletteSize 3 or 4, a 2-bit field is used; and for paletteSize + from 5 to 16, a 4-bit field is used. The bit fields are packed + into bytes, with the most significant bits representing the + leftmost pixel (i.e., big endian). For tiles not a multiple of 8, + 4, or 2 pixels wide (as appropriate), padding bits are used to + align each row to an exact number of bytes. + + +----------------------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +----------------------------+--------------+--------------+ + | paletteSize*bytesPerCPixel | CPIXEL array | palette | + | m | U8 array | packedPixels | + +----------------------------+--------------+--------------+ + + where m is the number of bytes representing the packed pixels. + For paletteSize of 2, this is div(width+7,8)*height; for + paletteSize of 3 or 4, this is div(width+3,4)*height; or for + paletteSize of 5 to 16, this is div(width+1,2)*height. + + 17 to 126: Unused. (Packed palettes of these sizes would offer no + advantage over palette RLE). + + 127: Packed palette with the palette reused from the previous tile. + The subencoding byte is followed by the packed pixels as described + above for packed palette types. + + 128: Plain RLE. The data consists of a number of runs, repeated + until the tile is done. Runs may continue from the end of one row + to the beginning of the next. Each run is represented by a single + pixel value followed by the length of the run. The length is + represented as one or more bytes. The length is calculated as one + more than the sum of all the bytes representing the length. Any + byte value other than 255 indicates the final byte. So for + + + + +Richardson & Levine Informational [Page 28] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + example, length 1 is represented as [0], 255 as [254], 256 as + [255,0], 257 as [255,1], 510 as [255,254], 511 as [255,255,0], and + so on. + + +-------------------------+--------------+-----------------------+ + | No. of bytes | Type [Value] | Description | + +-------------------------+--------------+-----------------------+ + | bytesPerCPixel | CPIXEL | pixelValue | + | div(runLength - 1, 255) | U8 array | 255 | + | 1 | U8 | (runLength-1) mod 255 | + +-------------------------+--------------+-----------------------+ + + 129: Palette RLE with the palette reused from the previous tile. + Followed by a number of runs, repeated until the tile is done, as + described below for 130 to 255. + + 130 to 255: Palette RLE. Followed by the palette, consisting of + paletteSize = (subencoding - 128) pixel values: + + +----------------------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +----------------------------+--------------+-------------+ + | paletteSize*bytesPerCPixel | CPIXEL array | palette | + +----------------------------+--------------+-------------+ + + Following the palette is, as with plain RLE, a number of runs, + repeated until the tile is done. A run of length one is + represented simply by a palette index: + + +--------------+--------------+--------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+--------------+ + | 1 | U8 | paletteIndex | + +--------------+--------------+--------------+ + + A run of length more than one is represented by a palette index + with the top bit set, followed by the length of the run as for + plain RLE. + + +-------------------------+--------------+-----------------------+ + | No. of bytes | Type [Value] | Description | + +-------------------------+--------------+-----------------------+ + | 1 | U8 | paletteIndex + 128 | + | div(runLength - 1, 255) | U8 array | 255 | + | 1 | U8 | (runLength-1) mod 255 | + +-------------------------+--------------+-----------------------+ + + + + + +Richardson & Levine Informational [Page 29] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +7.7.6. ZRLE + + ZRLE stands for Zlib (see [RFC1950] and [RFC1951]) Run-Length + Encoding, and combines an encoding similar to TRLE with zlib + compression. On the wire, the rectangle begins with a 4-byte length + field, and is followed by that many bytes of zlib-compressed data. A + single zlib "stream" object is used for a given RFB protocol + connection, so that ZRLE rectangles must be encoded and decoded + strictly in order. + + +--------------+--------------+-------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+-------------+ + | 4 | U32 | length | + | length | U8 array | zlibData | + +--------------+--------------+-------------+ + + The zlibData when uncompressed represents tiles in left-to-right, + top-to-bottom order, similar to TRLE, but with a tile size of 64x64 + pixels. If the width of the rectangle is not an exact multiple of + 64, then the width of the last tile in each row is smaller, and if + the height of the rectangle is not an exact multiple of 64, then the + height of each tile in the final row is smaller. + + The tiles are encoded in exactly the same way as TRLE, except that + subencoding may not take the values 127 or 129, i.e., palettes cannot + be reused between tiles. + + The server flushes the zlib stream to a byte boundary at the end of + each ZRLE-encoded rectangle. It need not flush the stream between + tiles within a rectangle. Since the zlibData for a single rectangle + can potentially be quite large, clients can incrementally decode and + interpret the zlibData but must not assume that encoded tile data is + byte aligned. + +7.8. Pseudo-Encodings + + An update rectangle with a "pseudo-encoding" does not directly + represent pixel data but instead allows the server to send arbitrary + data to the client. How this data is interpreted depends on the + pseudo-encoding. + +7.8.1. Cursor Pseudo-Encoding + + A client that requests the Cursor pseudo-encoding is declaring that + it is capable of drawing a pointer cursor locally. This can + significantly improve perceived performance over slow links. The + server sets the cursor shape by sending a rectangle with the Cursor + + + +Richardson & Levine Informational [Page 30] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + pseudo-encoding as part of an update. The rectangle's x-position and + y-position indicate the hotspot of the cursor, and width and height + indicate the width and height of the cursor in pixels. The data + consists of width*height raw pixel values followed by a shape + bitmask, with one bit corresponding to each pixel in the cursor + rectangle. The bitmask consists of left-to-right, top-to-bottom scan + lines, where each scan line is padded to a whole number of bytes, the + number being div(width+7,8). Within each byte, the most significant + bit represents the leftmost pixel; a bit set to 1 means the + corresponding pixel in the cursor is valid. + + +----------------------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +----------------------------+--------------+---------------+ + | width*height*bytesPerPixel | PIXEL array | cursor-pixels | + | div(width+7,8)*height | U8 array | bitmask | + +----------------------------+--------------+---------------+ + +7.8.2. DesktopSize Pseudo-Encoding + + A client that requests the DesktopSize pseudo-encoding is declaring + that it is capable of coping with a change in the framebuffer width + and height. The server changes the desktop size by sending a + rectangle with the DesktopSize pseudo-encoding as the last rectangle + in an update. The rectangle's x-position and y-position are ignored, + and width and height indicate the new width and height of the + framebuffer. + + There is no further data associated with the rectangle. After + changing the desktop size, the server must assume that the client no + longer has the previous framebuffer contents. This will usually + result in a complete update of the framebuffer at the next update. + However, for maximum interoperability with existing servers the + client should preserve the top-left portion of the framebuffer + between the old and new sizes. + +8. IANA Considerations + + IANA has allocated port 5900 to the RFB protocol. The other port + numbers mentioned in Section 2 are called out for historical context + and do not match IANA allocations. + + Future assignments to the IANA registries created by this + specification are to be made through either "Expert Review" or "IESG + Approval" (if there is no currently appointed expert) as defined in + [RFC5226]. + + + + + +Richardson & Levine Informational [Page 31] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +8.1. RFB Security Types + +8.1.1. Registry Name + + The name of this registry is "Remote Framebuffer Security Types". + +8.1.2. Registry Contents + + IANA established a registry for security types that are used with the + RFB protocol. + + The initial entries in the registry are: + + +------------+-------------------------+-----------------------+ + | Number | Name | References | + +------------+-------------------------+-----------------------+ + | 0 | Invalid | (this document) | + | 1 | None | (this document) | + | 2 | VNC Authentication | (this document) | + | 3 to 15 | RealVNC | (historic assignment) | + | 16 | Tight | (historic assignment) | + | 17 | Ultra | (historic assignment) | + | 18 | TLS | (historic assignment) | + | 19 | VeNCrypt | (historic assignment) | + | 20 | GTK-VNC SASL | (historic assignment) | + | 21 | MD5 hash authentication | (historic assignment) | + | 22 | Colin Dean xvp | (historic assignment) | + | 128 to 255 | RealVNC | (historic assignment) | + +------------+-------------------------+-----------------------+ + +8.2. Client-to-Server Message Types + +8.2.1. Registry Name + + The name of this registry is "Remote Framebuffer Client-to-Server + Message Types". + +8.2.2. Registry Contents + + IANA established a registry for client-to-server message types that + are used with the RFB protocol. + + The initial entries in the registry are: + + + + + + + + +Richardson & Levine Informational [Page 32] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + +--------+------------------------------+-----------------------+ + | Number | Name | References | + +--------+------------------------------+-----------------------+ + | 0 | SetPixelFormat | (this document) | + | 2 | SetEncodings | (this document) | + | 3 | FramebufferUpdateRequest | (this document) | + | 4 | KeyEvent | (this document) | + | 5 | PointerEvent | (this document) | + | 6 | ClientCutText | (this document) | + | 127 | VMWare | (historic assignment) | + | 128 | Nokia Terminal Mode Spec | (historic assignment) | + | 249 | OLIVE Call Control | (historic assignment) | + | 250 | Colin Dean xvp | (historic assignment) | + | 251 | Pierre Ossman SetDesktopSize | (historic assignment) | + | 252 | tight | (historic assignment) | + | 253 | gii | (historic assignment) | + | 254 | VMWare | (historic assignment) | + | 255 | Anthony Liguori | (historic assignment) | + +--------+------------------------------+-----------------------+ + +8.3. Server-to-Client Message Types + +8.3.1. Registry Name + + The name of this registry is "Remote Framebuffer Server-to-Client + Message Types". + +8.3.2. Registry Contents + + IANA established a registry for server-to-client message types that + are used with the RFB protocol. + + The initial entries in the registry are: + + + + + + + + + + + + + + + + + + +Richardson & Levine Informational [Page 33] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + +--------+--------------------------+-----------------------+ + | Number | Name | References | + +--------+--------------------------+-----------------------+ + | 0 | FramebufferUpdate | (this document) | + | 1 | SetColourMapEntries | (this document) | + | 2 | Bell | (this document) | + | 3 | ServerCutText | (this document) | + | 127 | VMWare | (historic assignment) | + | 128 | Nokia Terminal Mode Spec | (historic assignment) | + | 249 | OLIVE Call Control | (historic assignment) | + | 250 | Colin Dean xvp | (historic assignment) | + | 252 | tight | (historic assignment) | + | 253 | gii | (historic assignment) | + | 254 | VMWare | (historic assignment) | + | 255 | Anthony Liguori | (historic assignment) | + +--------+--------------------------+-----------------------+ + +8.4. RFB Encoding Types + +8.4.1. Registry Name + + The name of this registry is "Remote Framebuffer Encoding Types". + +8.4.2. Registry Contents + + IANA established a registry for encoding types that are used with the + RFB protocol. + + The initial entries in the registry are: + + + + + + + + + + + + + + + + + + + + + + +Richardson & Levine Informational [Page 34] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + +-------------------+----------------------------+------------------+ + | Number | Name | References | + +-------------------+----------------------------+------------------+ + | 0 | Raw | (this document) | + | 1 | CopyRect | (this document) | + | 2 | RRE | (this document) | + | 5 | Hextile | (this document) | + | 16 | ZRLE | (this document) | + | -239 | Cursor pseudo-encoding | (this document) | + | -223 | DesktopSize | (this document) | + | | pseudo-encoding | | + | 4 | CoRRE | (historic | + | | | assignment) | + | 6 | zlib | (historic | + | | | assignment) | + | 7 | tight | (historic | + | | | assignment) | + | 8 | zlibhex | (historic | + | | | assignment) | + | 15 | TRLE | (this document) | + | 17 | Hitachi ZYWRLE | (historic | + | | | assignment) | + | 1024 to 1099 | RealVNC | (historic | + | | | assignment) | + | -1 to -222 | tight options | (historic | + | | | assignment) | + | -224 to -238 | tight options | (historic | + | | | assignment) | + | -240 to -256 | tight options | (historic | + | | | assignment) | + | -257 to -272 | Anthony Liguori | (historic | + | | | assignment) | + | -273 to -304 | VMWare | (historic | + | | | assignment) | + | -305 | gii | (historic | + | | | assignment) | + | -306 | popa | (historic | + | | | assignment) | + | -307 | Peter Astrand DesktopName | (historic | + | | | assignment) | + | -308 | Pierre Ossman | (historic | + | | ExtendedDesktopSize | assignment) | + | -309 | Colin Dean xvp | (historic | + | | | assignment) | + | -310 | OLIVE Call Control | (historic | + | | | assignment) | + | -412 to -512 | TurboVNC fine-grained | (historic | + | | quality level | assignment) | + + + +Richardson & Levine Informational [Page 35] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + | -523 to -524 | Nokia Terminal Mode Spec | (historic | + | | | assignment) | + | -763 to -768 | TurboVNC subsampling level | (historic | + | | | assignment) | + | 0x574d5600 to | VMWare | (historic | + | 0x574d56ff | | assignment) | + +-------------------+----------------------------+------------------+ + +9. Security + + The RFB protocol as defined here provides no security beyond the + optional and cryptographically weak password check described in + Section 7.2.2. In particular, it provides no protection against + observation of or tampering with the data stream. It has typically + been used on secure physical or virtual networks. + + Security methods beyond those described here may be used to protect + the integrity of the data. The client and server might agree to use + an extended security type to encrypt the session, or the session + might be transmitted over a secure channel such as IPsec [RFC4301] or + SSH [RFC4254]. + +10. Acknowledgements + + James Weatherall, Andy Harter, and Ken Wood also contributed to the + design of the RFB protocol. + + RFB and VNC are registered trademarks of RealVNC Ltd. in the U.S. and + in other countries. + +11. References + +11.1. Normative References + + [RFC1950] Deutsch, L. and J-L. Gailly, "ZLIB Compressed Data Format + Specification version 3.3", RFC 1950, May 1996. + + [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification + version 1.3", RFC 1951, May 1996. + + [XLIBREF] Nye, A., "XLIB Reference Manual R5", June 1994. + +11.2. Informative References + + [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) + Connection Protocol", RFC 4254, January 2006. + + + + + +Richardson & Levine Informational [Page 36] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + [RFC4301] Kent, S. and K. Seo, "Security Architecture for the + Internet Protocol", RFC 4301, December 2005. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Richardson & Levine Informational [Page 37] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + +Appendix A. Differences in Earlier Protocol Versions + + For maximum interoperability, clients and servers should be prepared + to fall back to the earlier 3.3 and 3.7 versions of the RFB protocol. + Any version reported other than 3.7 or 3.8 should be treated as 3.3. + + All of the differences occur in the initial handshake phase. Once + the session reaches the ClientInit and ServerInit messages, all three + protocol versions are identical. Even within a protocol version, + clients and servers may support different subsets of the encoding and + pseudo-encoding types. + +A.1. Differences in the Version 3.3 Protocol + + The ProtocolVersion message is: + + RFB 003.003\n (hex 52 46 42 20 30 30 33 2e 30 30 33 0a) + + In the security handshake (Section 7.1.2), rather than a two-way + negotiation, the server decides the security type and sends a single + word: + + +--------------+--------------+---------------+ + | No. of bytes | Type [Value] | Description | + +--------------+--------------+---------------+ + | 4 | U32 | security-type | + +--------------+--------------+---------------+ + + The security-type may only take the value 0, 1, or 2. A value of 0 + means that the connection has failed and is followed by a string + giving the reason, as described in Section 7.1.2. + + If the security-type is 1, for no authentication, the server does not + send the SecurityResult message but proceeds directly to the + initialization messages (Section 7.3). + + In VNC Authentication (Section 7.2.2), if the authentication fails, + the server sends the SecurityResult message, but does not send an + error message before closing the connection. + +A.2. Differences in the Version 3.7 Protocol + + The ProtocolVersion message is: + + RFB 003.007\n (hex 52 46 42 20 30 30 33 2e 30 30 37 0a) + + + + + + +Richardson & Levine Informational [Page 38] + +RFC 6143 The Remote Framebuffer Protocol March 2011 + + + After the security handshake, if the security-type is 1, for no + authentication, the server does not send the SecurityResult message + but proceeds directly to the initialization messages (Section 7.3). + + In VNC Authentication (Section 7.2.2), if the authentication fails, + the server sends the SecurityResult message, but does not send an + error message before closing the connection. + +Authors' Addresses + + Tristan Richardson + RealVNC Ltd. + Betjeman House, 104 Hills Road + Cambridge CB2 1LQ + UK + + Phone: +44 1223 310400 + EMail: standards@realvnc.com + URI: http://www.realvnc.com + + + John Levine + RealVNC Ltd. + + Phone: +44 1223 790005 + EMail: standards@taugh.com + URI: http://jl.ly + + + + + + + + + + + + + + + + + + + + + + + + +Richardson & Levine Informational [Page 39] + |