Basic Introduction to Spice protocol-----and definitions of common protocols

1 Spice Protocol Introduction

The spice protocol defines a set of protocol messages to access, control, and receive operations over the network from a remote computer device (such as a keyboard, video, mouse), and reply to the send output. The control device can be either on the client or on the server side. In addition, the Protocol defines a set of supported remote servers to migrate from one network address to another network address. Encrypted transmission of data, with one exception, in the choice of encryption method is more flexible. Spice uses simple messaging and does not rely on any RPC standard or a specific transport layer.

Spice communication sessions are divided into multiple communication channels (one for each remote device) in order to have the ability to control communication and execute messages based on the channel type (such as QoS encryption), and to add and remove channels at runtime (Spice customization is supported).

1) main channel as the main spice session channel

2) display channel receive remote display update

3) input channel sends mouse and keyboard events

4) Cursor channel receive pointer shape and position

5) Playback channel receive audio stream

6) The recording channel sends the client audio input.

As the protocols evolve to add more channel types, spice also defines a set of protocol synchronization channels to be executed at the remote site.

2 General Protocol Definition 2.1 byte order

Unless otherwise specified, all data structure wrappers and byte-bit order are in the small segment byte format.

2.2 Protocol version

The protocol version is defined as two UINT32 values, the primary protocol version and the minor protocol version. The server and client have the same major version, in order to maintain compatibility regardless of the minor version number.

? Red_version_major = 1

? Red_version_minor = 0

2.3 Channel Type-uint8

? Red_channel_main = 1

? Red_channel_display = 2

? Red_channel_inputs = 3

? Red_channel_cursor = 4

? Red_channel_playback = 5

? Red_channel_record = 6

2.4 Channel Link-establish a channel connection 2.4.1 connection process

The channel connection process is initiated by the client. The client sends the redlinkmess as the response server sends the redlinkreply. When the client receives the redlinkreply, it checks the return error code, and if there is no error it encrypts the public key password in redlinkreply and sends it to the server. The server receives the password and sends the result of the link to the client. The client checks the results of the connection and, if the result is RED_ERROR_OK, establishes a valid link. The channel types other than Red_channel_main only allow the client to actively connect Red_channel_main. A session with a remote server is established only after the Red_channel_main channel is allowed.

2.4.2 Ticketing

Ticketing is an implementation mechanism of the spice protocol to ensure that only authorized source connections are allowed. To ensure this mechanism, ticketing is a component that has a password and a valid time period on the spice server side. After the time expires, this ticketing also expires. This ticketing is encrypted. In order to use encryption, the server generates a 1024-bit RSA key and sends the public key (via Redlinkinfo) to the client. The client uses this public key to encrypt the password and send it back to the server (after redlinkmess). The server decrypts the password, compares its ticketing and ensures that it is within the allowed time frame.

2.4.3 redlinkmess Definition

typedef structspice_attr_packed Spicelinkheader {

Uint32_t Magic; Must be a red_magic

uint32_t major_version; Client Major Version number

uint32_t minor_version;//Client Minor version number

uint32_t size; Size of subsequent data

}spicelinkheader;

typedef structspice_attr_packed Spicelinkmess {

uint32_t connection_id; For a new session (for example, Red_channel_main) This value is set to 0 and the server assigns the session ID and sends it to the client in the redlinkmess message. Other channel types. Use the assigned session ID.

uint8_t Channel_type; Channel type

uint8_t channel_id; Channel ID, the same ID may have more than one channel.

uint32_t num_common_caps;//Common Client channel functional terms number

uint32_t num_channel_caps; Number of special client channel functional words

uint32_t Caps_offset; The size of the structure. The following also has the ability to set the value

} spicelinkmess;

2.4.4 redlinkreply Definition

typedef structspice_attr_packed Spicelinkheader {   uint32_t magic;             Must be red_magic    uint32_t major_version;//Server major version    uint32_t minor_version;//Server minor version number    uint32_t size;                     Subsequent data size}spicelinkheader;typedef structspice_attr_packed spicelinkreply {    uint32_t error;          Version number negotiation result, error code    uint8_t pub_key[spice_ticket_pubkey_bytes];//Public key    uint32_t num_common_caps;  Common server channel function word number    uint32_t num_channel_caps;   Common server channel function word number    uint32_t caps_offset;         Offset}spicelinkreply;

2.4.5 Encryption Password

Client sends back to server using public key encryption password

2.4.6 Validation Results

Receive validation results

2.5 Protocol Message Definition

After the connection is established, all message transmissions follow the following format. Begins at Reddataheader describes a primary message and an optional sub-message. Use Spiceminidataheader in the actual transfer. 2.5.2, 2.5.3, 2.5.4 structures are no longer explained in detail.

2.5.1 Spiceminidataheader

typedef structspice_attr_packed Spiceminidataheader {

uint16_t type; Message type, select the respective handler function based on the channel type.

uint32_t size;//Data size

} Spiceminidataheader;

2.5.2 Spicedataheader

The data header is not used in the actual transmission and the following mini_header is used.

typedef structspice_attr_packed Spicedataheader {

uint64_t serial; The serial number of the message within the channel. started at 1, followed by a gradual increase

uint16_t type; Message type

uint32_t size; The size of the message body, if sublist is not 0, then sub_list is the actual size of the message

uint32_t Sub_list;//offset to spicesubmessagelist[]//subsequent data size

}spicedataheader;

2.5.3 Spicesubmessage

typedef structspice_attr_packed Spicesubmessage {

uint16_t type;

uint32_t size;

}spicesubmessage;

2.5.4 Spicesubmessagelist

typedef structspice_attr_packed Spicesubmessagelist {

uint16_t size;

uint32_t Sub_messages[0]; Offsets Tospicedsubmessage

}spicesubmessagelist;

2.6 Common message and message-passing naming conventions

The message and message body structure type prefixes describe the source of the message. Specific as follows:

Server---Client: RED

Client---server: REDC

this name is SPICE The description in the protocol document, in the actual source code, may be the following definition:

Server --- "Client: spice_msg

Client --- "Server: SPICE_MSGC

2.7Ping

The spice protocol provides a ping message for debugging purposes. The spice server sends red_ping, and the client responds to redc_ping. The server can use this debug to test the network situation. It can also be used to synchronize a channel of client and server time.

Description of 2.7.1 spicemsgping structural body

typedef structspicemsgping {

uint32_t ID; The ID of the message, the server is sent to the client, the client responds with this ID

uint64_t Timestamp of timestamp;//message

void *data; This data is of unknown use

uint32_t Data_len;

} spicemsgping;

2.8-Channel migration

Spice supports a spice server-side migration. This feature is not explained for the time being.

2.9-Channel synchronization

The Spice protocol provides the message to perform a synchronization mechanism on the client. The server sends a RED_WAIT_FOR_CHANNELS message that contains a channel list of message Waits (Redwaitforchannels). The spice client waits for all messages to complete this list before all other messages are executed.

Description of 2.9.1 Spicewaitforchannel structural body

typedef Structspicewaitforchannel {

uint8_t Channel_type; The category of the channel. 5 x

uint8_t channel_id; Channel ID

uint64_t message_serial;//the sequence ID number of the wait message

}spicewaitforchannel;

2.9.2 Spicemsgwaitforchannels; Description of structural body

typedef structspicemsgwaitforchannels {

uint8_t Wait_count; Number of wait messages

Spicewaitforchannel wait_list[0];//List of channels to wait

}spicemsgwaitforchannels;

2.10 Disconnect Reason

The following message is used to notify an ordered disconnect server or client

2.10.1 Spicemsgdisconnect Description

typedef Structspicemsgdisconnect {

uint64_t time_stamp;//The time stamp of the server or client disconnection

uint32_t reason; Spice_err_?

}spicemsgdisconnect;

2.11 Server Notification messages

The Spice protocol defines the interactive notification of the message to the client using the red_notify message. Messages can be classified as severity and visibility. It can be displayed to the user in the future as a message.

Description of 2.11.1 spicemsgnotify structural body

typedef structspicemsgnotify {

uint64_t Time_stamp; The timestamp of this message on the server side

uint32_t severity; Severity of the message

uint32_t visibilty; How visible the message is

uint32_t what; Categories of messages, errors, warnings, help, and so on

uint32_t message_len;//Message length

uint8_t Message[0]; Message data

}spicemsgnotify;

Basic Introduction to Spice protocol-----and definitions of common protocols