This document provides a comprehensive reference for the Deskflow network protocol. It is the primary source of information for developers implementing Deskflow clients or extending the protocol.

Protocol Overview

The Deskflow protocol enables keyboard and mouse sharing between multiple computers over a TCP network connection. The protocol uses two distinct sets of terminology to describe the roles of the computers involved:

Network Role (Client/Server): This describes the connection architecture.
- Server: The machine that listens for incoming TCP connections.
- Client: The machine that initiates the TCP connection to the server.
Input Control Role (Primary/Secondary): This describes the flow of keyboard and mouse events.
- Primary: The computer whose keyboard and mouse are currently being used to control other computers.
- Secondary: A computer that is being controlled by the Primary's keyboard and mouse.

In a typical setup, the Primary computer (the one whose keyboard and mouse are shared) also acts as the Server. However, the protocol is flexible and allows these roles to be separate. For example, a Primary machine can act as a Client to connect to a Secondary machine that is configured as a Server. This can be useful for navigating restrictive network environments like firewalls.

Throughout the documentation, message direction is often described using the Primary/Secondary roles to clarify the input control flow, while Client/Server roles are used when discussing the underlying network connection.

Key Implementation Files

ProtocolTypes.h – Complete protocol specification
ProtocolUtil.h – Message formatting utilities
ClientInfo – Screen information structure

The protocol is designed to be:

Lightweight and efficient
Cross-platform compatible
Extensible for new features
Backward compatible with older versions

Protocol Architecture

┌─────────────────┐    TCP/IP Network    ┌─────────────────┐
│   Primary       │◄────────────────────►│   Secondary     │
│   (Server)      │     Port 24800       │   (Client)      │
│                 │                      │                 │
│ • Shares input  │                      │ • Receives input│
│ • Manages layout│                      │ • Reports info  │
│ • Coordinates   │                      │ • Executes cmds │
└─────────────────┘                      └─────────────────┘

The protocol operates over a standard TCP connection on port 24800. In protocol versions 1.4 and later, TLS encryption is supported for secure communications.

Protocol State Machine

The client's connection lifecycle is defined by five primary states:

              ┌──────────────────┐
              │      START       │
              └────────┬─────────┘
                       │
                       ▼
              ┌────────┴─────────┐
              │   DISCONNECTED   │
              │   (Initial &     │◄───────────────────┐
              │   Final State)   │                    │
              └────────┬─────────┘                    │
                       │                              │
                       ▼                              │
              ┌──────────────────┐                    │
              │    CONNECTING    │  TCP Failure       │
              │  (TCP handshake) ├───────────────────►┤
              └────────┬─────────┘                    │
                       │                              │
           TCP Success │                              │
                       │                              │
                       ▼                              │
              ┌──────────────────┐                    │
              │    HANDSHAKE     │  Version Mismatch  │
              │  (Hello/HelloBk) ├───────────────────►┤
              └────────┬─────────┘                    │
                       │                              │
                    OK │                              │
                       │                              │
                       ▼                              │
              ┌──────────────────┐                    │
              │    CONNECTED     │  CCLOSE (close)    │
         ┌───►│  (Authenticated  ├───────────────────►┤
         │    │   but inactive)  │                    │
         │    └────────┬─────────┘                    │
         │             │                              │
  COUT   │        CINN │                              │
(Leave)  │      (Enter)│                              │
         │             ▼                              │
         │    ┌──────────────────┐                    │
         └────┤      ACTIVE      │  CCLOSE (close)    │
              │  (Receiving all  ├───────────────────►┘
         ┌───►│   input events)  │
         │    └────────┬─────────┘
         │             │
         │             ▼
         │    ┌──────────────────┐
         └────┤  PROCESS EVENT   │
              └──────────────────┘

State Descriptions

Disconnected: Initial and final state. No connection to Server.
Connecting: TCPSocket connection attempt in progress.
- Initiating TCPSocket connection.
- On successful TCP connection, moves to the Handshake state.
- If TCP connection fails (timeout, RST packet), returns to Disconnected.
Handshake: Protocol version negotiation and authentication.
- Server sends kMsgHello with protocol version information.
- Client responds with kMsgHelloBack including version and screen name.
- Server validates the client's message.
- Success transitions to Connected, failure sends kMsgEIncompatible error.
Connected: Authenticated but not receiving input events.
- Client must respond to kMsgCKeepAlive messages from the Server.
- Receiving kMsgCEnter message transitions to Active.
Active: Receiving and processing input events from Server.
- Receiving kMsgCLeave message transitions back to Connected.
- Receiving kMsgCClose message transitions to Disconnected.

Message Categories

The protocol organizes messages into logical categories:

Category	Prefix	Purpose	Examples
Handshake	None	Connection setup	kMsgHello, kMsgHelloBack
Commands	C	Screen control	kMsgCEnter, kMsgCLeave, kMsgCKeepAlive
Data	D	Input events	kMsgDKeyDown, kMsgDMouseMove, kMsgCClipboard, kMsgDClipboard
Queries	Q	Information requests	kMsgQInfo
Errors	E	Error notifications	kMsgEIncompatible, kMsgEBusy

Message Reference Table

This table lists all protocol messages in alphabetical order. For a typical sequence of messages, see the Typical Control Flow section.

Message	Constant	Category	Direction	Purpose	Constraints	Protocol Version
CALV	kMsgCKeepAlive	Command	Both	Keep-alive	MsgSize, KeepAlive	1.3+
CBYE	kMsgCClose	Command	Server→Client	Close connection	MsgSize	1.0+
CCLP	kMsgCClipboard	Command	Both	Clipboard ownership notification	MsgSize	1.0+
CIAK	kMsgCInfoAck	Command	Server→Client	Acknowledge info message	MsgSize	1.0+
CINN	kMsgCEnter	Command	Server→Client	Enter screen	MsgSize, ScreenEntrySync	1.0+
CNOP	kMsgCNoop	Command	Both	No operation	MsgSize	1.0+
COUT	kMsgCLeave	Command	Server→Client	Leave screen	MsgSize	1.0+
CROP	kMsgCResetOptions	Command	Server→Client	Reset options to defaults	MsgSize	1.0+
CSEC	kMsgCScreenSaver	Command	Server→Client	Screen saver control	MsgSize	1.0+
DCLP	kMsgDClipboard	Data	Both	Clipboard data	MsgSize	1.0+
DDRG	kMsgDDragInfo	Data	Server→Client	Drag file info	MsgSize, ListSize	1.5+
DFTR	kMsgDFileTransfer	Data	Both	File transfer data	MsgSize	1.5+
DINF	kMsgDInfo	Data	Client→Server	Screen information	MsgSize	1.0+
DKDL	kMsgDKeyDownLang	Data	Server→Client	Key down with language	MsgSize, KeyMap	1.8+
DKDN	kMsgDKeyDown	Data	Server→Client	Key down	MsgSize, KeyMap	1.1+
DKDN	kMsgDKeyDown1_0	Data	Server→Client	Key down (legacy)	MsgSize, KeyMap	1.0
DKRP	kMsgDKeyRepeat	Data	Server→Client	Key repeat	MsgSize, KeyMap	1.1+
DKRP	kMsgDKeyRepeat1_0	Data	Server→Client	Key repeat (legacy)	MsgSize, KeyMap	1.0
DKUP	kMsgDKeyUp	Data	Server→Client	Key up	MsgSize, KeyMap	1.1+
DKUP	kMsgDKeyUp1_0	Data	Server→Client	Key up (legacy)	MsgSize, KeyMap	1.0
DMDN	kMsgDMouseDown	Data	Server→Client	Mouse down	MsgSize	1.0+
DMMV	kMsgDMouseMove	Data	Server→Client	Mouse move (absolute)	MsgSize	1.0+
DMRM	kMsgDMouseRelMove	Data	Server→Client	Mouse move (relative)	MsgSize	1.2+
DMUP	kMsgDMouseUp	Data	Server→Client	Mouse up	MsgSize	1.0+
DMWM	kMsgDMouseWheel	Data	Server→Client	Mouse wheel	MsgSize	1.3+
DMWM	kMsgDMouseWheel1_0	Data	Server→Client	Mouse wheel (legacy)	MsgSize	1.0-1.2
DSOP	kMsgDSetOptions	Data	Server→Client	Set options	MsgSize, ListSize	1.0+
EBAD	kMsgEBad	Error	Server→Client	Protocol violation	MsgSize	1.0+
EBSY	kMsgEBusy	Error	Server→Client	Server busy	MsgSize	1.0+
EICV	kMsgEIncompatible	Error	Server→Client	Incompatible version	MsgSize	1.0+
EUNK	kMsgEUnknown	Error	Server→Client	Unknown client	MsgSize	1.0+
Hello	kMsgHello	Handshake	Server→Client	Protocol identification	HelloSize, MsgSize	1.0+
HelloArgs	kMsgHelloArgs	Handshake	Internal	Hello message construction	HelloSize, MsgSize	1.0+
HelloBack	kMsgHelloBack	Handshake	Client→Server	Client identification	HelloSize, MsgSize, HandshakeTimeout	1.0+
HelloBackArgs	kMsgHelloBackArgs	Handshake	Internal	HelloBack message construction	HelloSize, MsgSize, HandshakeTimeout	1.0+
LSYN	kMsgDLanguageSynchronisation	Data	Server→Client	Language synchronization	MsgSize	1.8+
QINF	kMsgQInfo	Query	Server→Client	Request screen info	MsgSize	1.0+
SECN	kMsgDSecureInputNotification	Data	Server→Client	Secure input notification	MsgSize	1.7+

Typical Control Flow

A typical control flow is as follows:

Handshake: The server and client exchange Hello and HelloBack messages to agree on a protocol version.
Information Exchange: The server requests client information with QINF, and the client responds with DINF.
Options: The server sends DSOP to configure client options.
Keep-Alive: The server and client periodically exchange CALV messages to maintain the connection.
Screen Entry: The server sends CINN to grant control to the client.
Input Events: The server sends a stream of input event messages (e.g., DMMV, DMDN, DKDN).
Screen Leave: The server sends COUT to revoke control from the client.
Connection Close: The server sends CCLOSE to terminate the connection.

Protocol Constraints

To ensure security, stability, and compatibility, the protocol enforces strict constraints:

Message and Data Size Limits

Maximum Message Size:
4,194,304 bytes (4 MB) — PROTOCOL_MAX_MESSAGE_LENGTH
Maximum total size of any single, length-prefixed data packet
Defined in Protocol Limits

Maximum List Size:
1,048,576 elements — PROTOCOL_MAX_LIST_LENGTH
Maximum number of items in a list/vector within a message
Defined in Protocol Limits

Maximum Hello Size:
1,024 bytes — kMaxHelloLength
Maximum size of the initial Connection Handshake message
Defined in Protocol Limits

TLS Handshake and Security (Protocol v1.4+)

When encryption is enabled, the protocol follows this sequence:

Standard TCP connection established
TLS handshake performed over TCP socket
Protocol handshake begins only after TLS session is established

Implementation Details:
- The client initiates a standard TCP connection, then the (private) SecureSocket::handleTCPConnected method is called, which begins the TLS handshake
Certificate Validation:
- Client implementations must validate the server's certificate
- The reference implementation checks that the public key is RSA or DSA and that the key length is at least 2048 bits

Key Code and Modifier Mapping

A modifier (modifier mask) represents the state of modifier keys (like Shift, Control, Alt, and Command) on a keyboard. It is a binary code (like 0000 0110) where each bit corresponds to a specific modifier key.

Key-Up/Key-Down Strategy:

Client must use the KeyButton (physical key) to track pressed keys, as the KeyID (virtual key) can change based on modifier state

This strategy is described in the documentation for kMsgDKeyDown

Modifier Remapping:

The server can command clients to remap modifier keys via the kMsgDSetOptions message
The client processes the kMsgDSetOptions message and updates the modifier translation table accordingly

Timing and Synchronization

Keep-Alive Mechanism (Protocol v1.3+)

Server-Side Behavior:

The server sends kMsgCKeepAlive messages every 3.0 seconds (defined by kKeepAliveRate)
This timer is implemented in ClientProxy1_3::addHeartbeatTimer in the ClientProxy1_3 class

Client-Side Behavior:

Upon receiving a kMsgCKeepAlive message, the client must immediately send a kMsgCKeepAlive message back
The client maintains a timeout that is reset each time any message is received
If no message is received for 9.0 seconds (3 × kKeepAliveRate), client must disconnect
This is handled by the (private) ServerProxy::handleKeepAliveAlarm method

Synchronization on Screen Entry

The kMsgCEnter (Enter Screen) message includes the current modifier state
Client must synchronize their local modifier state with this mask

Handshake Timeout

Server allows 30 seconds for handshake completion
If client fails to send valid kMsgHelloBack within this time, connection is closed
When a new client connects, the server creates a temporary ClientProxyUnknown to handle the version handshake
A one-shot timer is started for 30 seconds
If the client fails to respond in time, the Error Messages function is triggered, the connection is logged as unresponsive, and the socket is closed

Version Compatibility

Version	Release Date	Project	Features	Compatibility
1.0	May 2001	Synergy	Basic keyboard/mouse sharing (kMsgDKeyDown, kMsgDMouseMove)	All versions
1.1	Apr 2002	Synergy	Physical key codes (KeyButton)	1.1+
1.2	Jan 2006	Synergy	Relative mouse movement	1.2+
1.3	May 2006	Synergy	Keep-alive (kMsgCKeepAlive), horizontal scroll (kMsgDMouseWheel)	1.3+
1.4	Nov 2012	Synergy	Encryption support (SecureSocket)	1.4+
1.5	Sep 2013	Synergy	File transfer	1.5+
1.6	Jan 2014	Synergy	Clipboard streaming	1.6+
1.7	Nov 2021	Synergy	Secure input notifications	1.7+
1.8	Jun 2025	Synergy	Language synchronization	1.8+

Version Migration Guide

When implementing a client that supports multiple protocol versions:

Version Negotiation: During handshake, client should advertise highest supported version
Feature Detection: Check server's version in Hello message before using version-specific features
Fallback Mechanism: Be prepared to operate with only features available in the negotiated version
Graceful Degradation: If server supports a lower version than client's minimum, handle EIncompatible error gracefully

Implementation Examples

Connection Lifecycle

// 1. Connect to server
std::string server_ip = "192.168.1.100";
connect(server_ip, 24800);
 
// 2. Receive Hello from server
auto hello = receive_message();
std::string server_version, server_name;
parse_hello(hello, &server_version, &server_name);
 
// 3. Send HelloBack to server
std::string client_version = "1.8";
std::string client_name = "MyClient";
send_hello_back(client_version, client_name);
 
// 4. Enter main message loop
bool connected = true;
while (connected) {
    auto message = receive_message();
    handle_message(message);
}

Message Handling

void handle_message(const Message& msg) {
    switch (msg.type) {
        case "CINN": // Enter screen
            handle_enter(msg.x, msg.y, msg.sequence, msg.modifiers);
            break;
        case "DKDN": // Key down
            handle_key_down(msg.key_id, msg.modifiers, msg.key_button);
            break;
        case "DMMV": // Mouse move
            handle_mouse_move(msg.x, msg.y);
            break;
        // ... handle other message types
    }
}

Complete Message Exchange Sequence

Below is a typical message exchange sequence for a client connecting to a server:

Client                                 Server
  |                                      |
  |                                      | Server starts listening on port 24800
  |                                      |
  | TCP SYN                              |
  | ───────────────────────────────────► |
  |                                      |
  | ◄─────────────────────────────────── |
  | TCP SYN+ACK                          |
  |                                      |
  | TCP ACK                              |
  | ───────────────────────────────────► |
  |                                      | TCP connection established
  |                                      |
  | ◄─────────────────────────────────── |
  | "Deskflow" + version (1.8)           | Hello message
  |                                      |
  | "Deskflow" + version + name          |
  | ───────────────────────────────────► | HelloBack message
  |                                      |
  | ◄─────────────────────────────────── |
  | "QINF"                               | Query screen info
  |                                      |
  | "DINF" + screen dimensions           |
  | ───────────────────────────────────► | Report screen info
  |                                      |
  | ◄─────────────────────────────────── |
  | "DSOP" + options                     | Set options
  |                                      |
  | ◄─────────────────────────────────── |
  | "CALV"                               | Keep-alive
  |                                      |
  | "CALV"                               |
  | ───────────────────────────────────► | Keep-alive response
  |                                      |
  | ◄─────────────────────────────────── |
  | "CINN" + x + y + seq + mask          | Enter screen
  |                                      |
  | ◄─────────────────────────────────── |
  | "DMMV" + x + y                       | Mouse move
  |                                      |
  | ◄─────────────────────────────────── |
  | "DMDN" + button                      | Mouse down
  |                                      |
  | ◄─────────────────────────────────── |
  | "DMUP" + button                      | Mouse up
  |                                      |
  | ◄─────────────────────────────────── |
  | "DKDN" + key + mask + button         | Key down
  |                                      |
  | ◄─────────────────────────────────── |
  | "DKUP" + key + mask + button         | Key up
  |                                      |
  | ◄─────────────────────────────────── |
  | "COUT"                               | Leave screen
  |                                      |
  | ◄─────────────────────────────────── |
  | "CCLOSE"                             | Close connection
  |                                      |
  | TCP FIN                              |
  | ◄─────────────────────────────────── |
  |                                      |
  | TCP FIN+ACK                          |
  | ───────────────────────────────────► |
  |                                      | Connection closed

Legend:

Hello message: kMsgHello
HelloBack message: kMsgHelloBack
Query screen info: kMsgQInfo
Report screen info: kMsgDInfo
Set options: kMsgDSetOptions
Keep-alive: kMsgCKeepAlive
Enter screen: kMsgCEnter
Mouse move: kMsgDMouseMove
Mouse down: kMsgDMouseDown
Mouse up: kMsgDMouseUp
Key down: kMsgDKeyDown
Key up: kMsgDKeyUp
Leave screen: kMsgCLeave
Close connection: kMsgCClose

Debugging and Troubleshooting

Common Issues

Version Mismatch: Check protocol version negotiation
Message Format: Validate message structure and parameters
Byte Order: Ensure network byte order for multi-byte integers
Keep-Alive: Implement proper keep-alive response
Screen Info: Send accurate screen dimensions and mouse position

Debug Tools

Wireshark: Capture and analyze network traffic
Protocol Logs: Enable verbose logging in Deskflow
Message Validation: Check message format against specification

Platform-Specific Implementations

For platform-specific implementation details, refer to:

ProtocolTypes.h – Complete protocol specification
ProtocolUtil.h – Message formatting utilities

Implementation Checklist

Basic Client Implementation

Connection Management
- TCP connection to server port 24800
- Protocol handshake (Hello/HelloBack)
- Version negotiation
- Keep-alive handling
Message Processing
- Message parsing and validation
- Command message handling (Enter/Leave)
- Input event processing (keyboard/mouse)
- Error handling and recovery
Screen Management
- Screen information reporting (DINF)
- Resolution change detection
- Mouse cursor positioning
Input Synthesis
- Keyboard event injection
- Mouse event injection
- Modifier key synchronization

Advanced Features

Clipboard Synchronization
- Clipboard grab notifications
- Data transfer (kMsgDClipboard - text, images, HTML)
- Streaming for large data (v1.6+)
File Transfer (v1.5+)
- Drag-and-drop initiation
- Chunked file transfer
- Progress tracking
Security Features
- TLS/SSL encryption (v1.4+)
- Secure input notifications (v1.7+)
- Input validation and limits

Reference Implementation

The ServerProxy class provides a reference implementation demonstrating:

Basic protocol handling
Message parsing and generation
Connection management
Input event processing

Contributing

When extending the protocol:

Maintain Compatibility: New features should be backward compatible
Update Documentation: Document new messages and parameters
Version Increment: Bump minor version for new features
Test Thoroughly: Verify with existing clients and servers

Support and Resources

ProtocolTypes.h – Complete protocol specification
ProtocolUtil.h – Message formatting utilities

This documentation is generated from the source code and is always up-to-date with the latest protocol implementation.