3.2 KiB
3.2 KiB
Proxy Forwarding Overview
In multi-server Minecraft networks, players connect through a front-facing reverse proxy (such as Velocity, BungeeCord, or Vine) that routes connections between lobbies and sub-servers without requiring players to reconnect.
Because backend servers receive TCP connections directly from the proxy machine rather than the player, the server must be informed of the player's genuine IP address, UUID, username, and skin properties.
Pumpkin provides native support for all three major proxy forwarding protocols in crates/pumpkin/src/net/proxy/.
The Proxy Forwarding Problem
Without secure proxy forwarding:
- IP Loss: Every connected player appears with the proxy's loopback or internal IP (breaking IP bans and geo-location).
- UUID Spoofing & Bypasses: Malicious users could connect directly to the backend server's port with any spoofed username or operator identity.
To prevent proxy bypasses, Pumpkin validates cryptographic secrets, tokens, or digital signatures sent by the proxy.
Comparison of Supported Protocols
| Protocol | Protocol Transport | Security / Cryptography | Replay Protection | Crate Module |
|---|---|---|---|---|
| BungeeCord | SHandshake server address string |
Optional token in profile properties (bungeeguard-token) |
None | pumpkin::net::proxy::bungeecord |
| Velocity | Login plugin message (velocity:player_info) |
Symmetric HMAC-SHA256 signature | None | pumpkin::net::proxy::velocity |
| Vine | Login plugin message (vine:player_info) |
Asymmetric Ed25519 digital signatures | 16-byte nonce challenge + 30s timestamp window | pumpkin::net::proxy::vine |
Lifecycle Architecture
- Player Authentication: The player connects to the proxy (BungeeCord, Velocity, or Vine) and authenticates against Mojang's session servers.
- Backend Connection: The proxy connects to Pumpkin over TCP and sends
SHandshake. - Data Forwarding:
- BungeeCord Mode: The proxy injects the player's remote IP, UUID, and properties directly into the
SHandshakehostname string (separated by null bytes\0). - Modern Mode (Velocity / Vine): Pumpkin sends
CLoginPluginRequeston a dedicated channel (velocity:player_infoorvine:player_info). The proxy signs the player profile using HMAC-SHA256 (Velocity) or Ed25519 (Vine) and replies withSLoginPluginResponse.
- BungeeCord Mode: The proxy injects the player's remote IP, UUID, and properties directly into the
- Validation & Session Initialization: Pumpkin validates the signature, binds the real IP and GameProfile to the
JavaClient, and sendsCLoginSuccess.
Proxy Documentation
- BungeeCord: Legacy host string injection and optional BungeeGuard token validation.
- Velocity Modern Forwarding: HMAC-SHA256 signed player info during the Login state.
- Vine Modern Forwarding: Next-generation proxy forwarding with Ed25519 signatures and replay attack prevention.