XVP Extensions to the RFB Protocol

Colin Dean

Version 1
Last updated 24 November 2009

Contents

  1. Introduction
  2. Registered Security Types, Pseudo-Encodings and Message Types
  3. Security
  4. Initialisation Messages
  5. Operation Messages
  6. Acknowledgements

1. Introduction

This document describes the XVP extensions to the RFB Protocol published by RealVNC Ltd. The extensions are also fully documented in the community version of the RFB protocol specification.

These extensions were devised by Colin Dean to allow VNC-based clients to perform administrative operations (shutdown, reboot and reset) on virtual machines hosted on Citrix® XenServer, via the Xen VNC Proxy (xvp). These extensions are supported by xvp, and its associated client, xvpviewer, and also by recent versions of the ggivnc viewer.

The extensions are intended to be sufficiently general that they could be implemented at the server end for other virtualisation platforms, not just Citrix XenServer.

2. Registered Security Type, Pseudo-Encoding and Message Type

A new security type is used by xvp:

NumberName
22xvp

and also a new pseudo-encoding:

NumberName
-309xvp

and message type:

NumberName
250xvp

The message is used client to server and server to client, with the same format:

No.of bytesType [Value]Description
1U8      250message type
1 padding
1U8        1xvp extension version
1U8xvp message code

The following xvp message codes are defined:

ValueNameDirection
0XVP_FAILserver to client
1XVP_INITserver to client
2XVP_SHUTDOWNclient to server
3XVP_REBOOTclient to server
4XVP_RESETclient to server

3. Security

The xvp security type is used to implement XVP authentication, which is similar to standard VNC authentication, except that the client specifies a user name and a target name. This is used so that the server can implement (a) different passwords for different users, and (b) multiplexing of consoles for multiple target systems on a single TCP port.

Once XVP authentication has been selected, and before any challenge is sent from the server to the client, the client sends a message to the server of the form:

No.of bytesType [Value]Description
1U8user-length
1U8target-length
user-lengthU8 arrayuser-string
target-lengthU8 arraytarget-string

Either (or both) lengths may be zero, and the corresponding string omitted, to indicate a request for access as a default user and/or to a default target, although the server is not obliged to allow defaults.

The authentication dialog is then completed exactly as when using VNC authentication, i.e. with a challenge from server to client followed by a password-encrypted response from client to server.

The server should send a challenge, and await a response, even if it considers the user and/or target information to be invalid. This is to (a) limit the scope for malicious attacks which could otherwise probe for a valid user/target combination without having to know any passwords, and (b) allow a meaningful security result to be returned to the client (if using RFB version 3.8 or later).

4. Initialisation Messages

A client wishing to use the xvp extensions must signal this to the server by including the xvp pseudo-encoding (-309) in a SetEncodings message.

A server not supporting the xvp extensions will ignore this, but one that does support these extensions replies with a message of type xvp (250) and message code XVP_INIT. The server must specify in this message the highest xvp extension version it supports: the client may assume that the server supports all versions from 1 up to this value.

Only after this message has been received by the client, may it use the operation messages below. The client is free to use any xvp extension version supported by the server. Currently, only version 1 is defined.

5. Operation Messages

A client, having established that the server supports the xvp extensions, may request the server to perform an operation by sending a message of type xvp (250) with one of the following message codes:

OperationMessage Code
shutdown VM cleanlyXVP_SHUTDOWN
reboot VM cleanlyXVP_REBOOT
reset VM abruptlyXVP_RESET

Whereas the shutdown and reboot operations should be performed by the server in a way that allows the VM to save its data gracefully, the reset operation is intended to be analogous to ripping out and re-inserting the VM's power plug, and may result in data corruption (for instance, requiring a filesystem repair on restart).

If the server is unable to perform the operation, it must send a message of type xvp (250) with message code XVP_FAIL, and the same xvp extension version as included in the client's request. The client should convey failure to the user (for example, by displaying an alert, "Operation Failed").

If the server successfully performs the requested operation, it does not send a specific reply (success should be obvious from the contents of the VM's console framebuffer displayed by the client).

6. Acknowledgements

XVP is Copyright © 2009 Colin Dean, and is free software, distributable under the terms of the GNU General Public License. More information is available on the project web site: http://www.xvpsource.org/

Thanks to Peter Rosin for making me realise I needed to write this document, and for adding XVP support to ggivnc.

The VNC protocol was originally developed by the RealVNC team while at Olivetti Research Ltd / AT&T Laboratories Cambridge, UK. Thanks to Tristan Richardson of RealVNC for registering the XVP extensions.

Citrix® is a registered trademark and XenCenter™ a trademark of Citrix Systems, Inc.