MySQL Protocol Proxy

Relevant source files

The following files were used as context for generating this wiki page:

• warpgate-protocol-mysql/src/lib.rs
• warpgate-protocol-mysql/src/session.rs
• warpgate-protocol-mysql/src/client.rs
• warpgate-protocol-mysql/src/stream.rs
• warpgate-database-protocols/src/mysql/protocol/connect/handshake.rs
• warpgate-database-protocols/src/mysql/protocol/connect/auth_switch.rs
• warpgate/src/commands/setup.rs

The MySQL Protocol Proxy in Warpgate acts as a secure intermediary for MySQL database connections. It functions by intercepting incoming MySQL client connections, authenticating users against Warpgate's internal identity provider, and then establishing a proxied connection to the requested target MySQL database. Unlike a traditional jump host, Warpgate forwards connections directly to the target once authorized, while maintaining the ability to record and monitor the session.

Sources: README.md:27-31, warpgate-protocol-mysql/src/lib.rs:27-30

Architecture and Components

The MySQL proxy is built using a multi-layered approach that handles raw TCP streams, MySQL-specific packet framing, and high-level session logic.

Core Server Structure

The MySQLProtocolServer is the entry point for the MySQL service. It implements the ProtocolServer trait and manages the lifecycle of incoming connections.

• MySQLProtocolServer: Responsible for initializing the listener, loading TLS certificates, and spawning individual session handlers for each connection.
• MySqlSession: Manages the state machine of a single client connection, including handshakes, authentication, and the eventual proxying of SQL commands.
• MySqlClient: A specialized client used by Warpgate to connect to the upstream (target) MySQL server.

Sources: warpgate-protocol-mysql/src/lib.rs:21-30, warpgate-protocol-mysql/src/session.rs:31-43, warpgate-protocol-mysql/src/client.rs:18-21

Stream Handling

The system uses a custom MySqlStream wrapper to handle packet encoding/decoding and TLS upgrades.

The diagram shows how raw TCP data is wrapped in a TLS-aware stream and then decoded into MySQL packets using a PacketCodec.
Sources: warpgate-protocol-mysql/src/stream.rs:21-27

Data Flow and Session Lifecycle

1. Connection and Handshake

When a client connects, Warpgate initiates a MySQL handshake. It advertises its own capabilities (e.g., PROTOCOL_41, SSL, PLUGIN_AUTH) and provides an authentication challenge. Warpgate strictly requires TLS for these connections.

Sources: warpgate-protocol-mysql/src/session.rs:48-64, warpgate-protocol-mysql/src/session.rs:90-108

2. Authentication and Authorization

Warpgate supports two primary authentication methods for MySQL:

• Credential-based: The user provides a username formatted as user#target and a password.
• Ticket-based: The user provides a pre-generated secret ticket.

The sequence diagram illustrates the dual-handshake process where Warpgate first authenticates the user before establishing the upstream connection.
Sources: warpgate-protocol-mysql/src/session.rs:136-168, warpgate-protocol-mysql/src/session.rs:222-230

3. Command Proxying

Once authorized, the proxy enters a loop where it forwards MySQL commands (e.g., COM_QUERY, COM_INIT_DB) between the client and the target server.

• COM_QUERY (0x03): The proxy extracts the SQL query for logging purposes before passing it to the target.
• COM_QUIT (0x01): Terminates both the client and target connections.
• COM_INIT_DB (0x02): Updates the session's current database state.

Sources: warpgate-protocol-mysql/src/session.rs:327-360

Protocol Implementation Details

Handshake Structure

The Handshake packet is the first packet sent by the server to the client.

Field	Type	Description
protocol_version	u8	Always 10 for modern MySQL.
server_version	String	Warpgate identifies as 8.0.0-Warpgate.
server_capabilities	Capabilities	Bitmask of supported features (SSL, Plugin Auth, etc).
auth_plugin	AuthPlugin	Default is MySqlNativePassword.

Sources: warpgate-database-protocols/src/mysql/protocol/connect/handshake.rs:13-24, warpgate-protocol-mysql/src/session.rs:85-86

Target Connection Logic

The MySqlClient connects to the upstream target using options defined in the Warpgate configuration. It supports optional or required TLS for the upstream connection, independent of the client's TLS status.

// warpgate-protocol-mysql/src/client.rs:64-70
options.capabilities.remove(Capabilities::SSL);
if target.tls.mode != TlsMode::Disabled {
    options.capabilities |= Capabilities::SSL;
}

Sources: warpgate-protocol-mysql/src/client.rs:60-70

Configuration and Setup

During initial setup via warpgate setup, the MySQL service can be enabled and configured to listen on a specific endpoint.

Option	Type	Default Value	Description
mysql.enable	bool	true (Docker)	Whether to accept MySQL connections.
mysql.listen	ListenEndpoint	[::]:3306	The address and port for the proxy.
mysql.certificate	Path	tls.certificate.pem	Path to the TLS certificate.
mysql.key	Path	tls.key.pem	Path to the private key.

Sources: warpgate/src/commands/setup.rs:152-167, warpgate/src/commands/setup.rs:202-205

Conclusion

The MySQL Protocol Proxy provides a secure gateway for database access by enforcing TLS and centralizing authentication. By parsing the MySQL protocol at the packet level, it allows Warpgate to log SQL queries and manage session lifecycles without requiring modified client applications.