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