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.
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
1.**Disconnected**: Initial and final state. No connection to @ref Server.
2.**Connecting**: @ref TCPSocket connection attempt in progress.
- Initiating @ref TCPSocket connection.
- On successful TCP connection, moves to the `Handshake` state.
- If TCP connection fails (timeout, RST packet), returns to `Disconnected`.
3.**Handshake**: Protocol version negotiation and authentication.
-@ref Server sends @ref kMsgHello with protocol version information.
-@ref Client responds with @ref kMsgHelloBack including version and screen name.
-@ref Server validates the client's message.
- Success transitions to `Connected`, failure sends @ref kMsgEIncompatible error.
4.**Connected**: Authenticated but not receiving input events.
-@ref Client must respond to @ref kMsgCKeepAlive messages from the @ref Server.
- Receiving @ref kMsgCEnter message transitions to `Active`.
5.**Active**: Receiving and processing input events from @ref Server.
- Receiving @ref kMsgCLeave message transitions back to `Connected`.
- Receiving @ref kMsgCClose message transitions to `Disconnected`.
## Message Categories
The protocol organizes messages into logical categories:
This table lists all protocol messages in alphabetical order. For a typical sequence of messages, see the [Typical Control Flow](#typical-control-flow) section.
| Message | Constant | Category | Direction | Purpose | Constraints | Protocol Version |
| [**DCLP**](@ref kMsgDClipboard) | @ref kMsgDClipboard | Data | Both | Clipboard data | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DDRG**](@ref kMsgDDragInfo) | @ref kMsgDDragInfo | Data | Server→Client | Drag file info | [MsgSize](#constraint-protocol-max-message-length), [ListSize](#constraint-max-list) | 1.5+ |
| [**DFTR**](@ref kMsgDFileTransfer) | @ref kMsgDFileTransfer | Data | Both | File transfer data | [MsgSize](#constraint-protocol-max-message-length) | 1.5+ |
| [**DINF**](@ref kMsgDInfo) | @ref kMsgDInfo | Data | Client→Server | Screen information | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DKDL**](@ref kMsgDKeyDownLang) | @ref kMsgDKeyDownLang | Data | Server→Client | Key down with language | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.8+ |
| [**DKDN**](@ref kMsgDKeyDown) | @ref kMsgDKeyDown | Data | Server→Client | Key down | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.1+ |
| [**DKDN**](@ref kMsgDKeyDown1_0) | @ref kMsgDKeyDown1_0 | Data | Server→Client | Key down (legacy) | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.0 |
- 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:**
-<aid="constraint-keymap"></a>Client must use the @ref KeyButton (physical key) to track pressed keys, as the @ref KeyID (virtual key) can change based on modifier state
- This strategy is described in the documentation for @ref kMsgDKeyDown
**Modifier Remapping:**
- The server can command clients to remap modifier keys via the @ref kMsgDSetOptions message
- The client processes the @ref kMsgDSetOptions message and updates the modifier translation table accordingly
## Timing and Synchronization
<aid="constraint-keep-alive"></a>
### Keep-Alive Mechanism (Protocol v1.3+)
**Server-Side Behavior:**
- The server sends kMsgCKeepAlive messages every 3.0 seconds (defined by @ref kKeepAliveRate)
- This timer is implemented in @ref ClientProxy1_3::addHeartbeatTimer in the @ref 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 ×@ref kKeepAliveRate), client must disconnect
- The @ref kMsgCEnter (Enter Screen) message includes the current modifier state
- Client must synchronize their local modifier state with this mask
<aid="constraint-handshake-timeout"></a>
### Handshake Timeout
- Server allows **30 seconds** for handshake completion
- If client fails to send valid @ref kMsgHelloBack within this time, connection is closed
- When a new client connects, the server creates a temporary @ref ClientProxyUnknown to handle the version handshake
- A one-shot timer is started for 30 seconds
- If the client fails to respond in time, the @ref protocol_errors function is triggered, the connection is logged as unresponsive, and the socket is closed
## Version Compatibility
| Version | Release Date | Project | Features | Compatibility |
