Krypt04McgRelay

Warning

Due to personal reasons, this project is no longer maintained.

Warning

This codebase was generated with AI assistance. Review the implementation carefully, especially the cryptography, key storage, networking behavior, and dependency configuration, before using it in any real environment.

If possible, please run it in an ISOLATED environment, such as a virtual machine, to avoid potential security risks from build artifacts, such as the possibility that the maintainer’s computer has been infected with malware.

If you discover any code security issues, or any copyright or licensing concerns, please report them in Issues. Thank you for your understanding.

Warning

Krypt04Mcg is EXPERIMENTAL software and has not undergone independent security auditing. The protocol, implementation, and cryptographic design may contain vulnerabilities or design flaws. Do not rely on this mod to protect highly sensitive, important, or production-critical data. If you require mature and battle-tested end-to-end encrypted communication, consider using established tools such as Signal or SimpleX instead.

Disclaimer

Krypt04Mcg is an EXPERIMENTAL plugin project. Its build environment, release artifacts, dependencies, and runtime behavior are provided as-is, with NO GUARANTEE that they are secure, trustworthy, virus-free, or suitable for any particular use. Before installing or running any downloaded artifact, scan it with VirusTotal or a comparable malware-scanning service whenever possible.

Never use this project in production environments, and NEVER use it to protect sensitive, important, private, regulated, or high-value data. This project is not expected to receive active long-term maintenance, security response, or compatibility updates.

Krypt04McgRelay is a Bukkit/Spigot plugin that privately relays Krypt04Mcg encrypted chat packets. When a player sends a matching encrypted fragment, the server cancels the normal chat broadcast, rebuilds the packet header, reads the target receiver, and forwards the original encrypted fragments only to that player.

The server console never prints the encrypted payload. It logs a localized summary such as:

Alice sent an encrypted message to Bob.

Supported Server

Current plugin version: 1.9.0. See CHANGELOG.md for the per-player assembly and buffered-text limits, and their transport scope.

• Built against Spigot API 26.3-R0.1-SNAPSHOT.
• Uses Java 25 for Minecraft/Spigot 26.3.
• ProtocolLib is optional for the chat spam-kick bypass. The chat relay and custom payload channels work without it.
• Uses Bukkit API plus ProtocolLib packet interception, no NMS or CraftBukkit internals.

Packet Format

The plugin recognizes the fragment format used by the reference Krypt04Mcg client code:

[KRYPT04MCG] <messageId> <index> <total> <payload>

It waits until all fragments for the same sender and message id arrive, decodes the packet header, then routes the original fragment lines to the receiver stored in the encrypted packet metadata.

Packet protocol versions 1, 2, 3, and 4 are accepted. Protocol v3 no longer stores fragment metadata inside the encrypted packet, and omits KEM or signature algorithm identifiers when the packet type or flags do not use them. Protocol v4 session messages add a session ID and sequence number after the message ID and omit the signature field entirely. The relay handles all four packet types, including session exchanges and v4 session messages, while preserving the original encrypted fragments.

The custom payload channel krypt04mcg:chat_fragment is also supported. Its wire format remains two Minecraft UTF-8 strings followed by a VarInt version: client-to-server sends (receiver, fragment, version), and server-to-client sends (sender, fragment, version). The relay obtains the sender from the authenticated player connection and forwards the fragment and version unchanged. The receiving client must be listening on this channel.

Fragments forwarded through the vanilla chat transport use this chat shape:

<Alice> [KRYPT04MCG] <messageId> <index> <total> <payload>

This matches clients that parse incoming chat with:

^<(?<player>[^>]+)>\s*(?<message>.*)$

Configuration

config.yml is created on first run:

language: zh_cn
api-channel-count: 16
announce-plugin-installed: true
echo-to-sender: false
notify-offline-receiver: true
notify-malformed-fragment: true
enforce-sender-match: true
kick-krypt04mcg-chat-spam: false
fragment-timeout-seconds: 120
max-pending-messages: 128
max-fragments-per-message: 2048

kick-krypt04mcg-chat-spam is false by default. When it is false, Krypt04Mcg fragments do not count toward Minecraft chat spam kicks; when it is true, Krypt04Mcg fragments use the normal spam kick behavior. Non-Krypt04Mcg chat is not changed by this option.

The spam-kick bypass also covers Krypt04Mcg fragments sent through vanilla private-message commands (/tell, /msg, and /w). Other commands and ordinary private messages are not intercepted.

ProtocolLib is declared as a provided dependency and is not bundled into the Krypt04McgRelay jar. For Minecraft/Spigot 26.2, use a compatible GitHub development build. ProtocolLib's published source still lists 26.2 as its highest tested version, so packet interception on 26.3 is not yet verified. Without an enabled, compatible ProtocolLib build, the relay still handles ordinary chat and custom payloads, but cannot bypass vanilla chat spam kicks for encrypted fragments or private-message commands.

Language files are also created in the plugin data folder:

• messages_zh_cn.yml
• messages_en_us.yml

Set language to zh_cn or en_us, then run:

/kryptrelay reload

Set announce-plugin-installed to false if you do not want players to receive the plugin-installed notice. The notice tells compatible mod users to enable "Shadow Listen Mode".

Build

With Maven installed:

mvn package

The plugin jar will be generated as target/Krypt04McgRelay-1.9.0.jar.

GitHub Actions

The repository includes a GitHub Actions workflow at .github/workflows/build.yml. It builds the plugin on pushes, pull requests, and manual runs, then uploads the generated jar as a workflow artifact.

Release publishing is handled by .github/workflows/release.yml. Push the v1.9.0 tag, or run the workflow manually, to build the plugin and create a GitHub Release. If the RELEASE_SIGN_KEY secret is configured with a PEM private key, release jars are signed and the public key is uploaded with the release assets.

Install

1. Build the jar or download it from a release.
2. Put it into the server plugins/ directory.
3. To enable the chat spam-kick bypass, install a ProtocolLib build compatible with your server in the plugins/ directory.
4. Restart the server.
5. Edit the generated config if needed.
6. Run /kryptrelay reload after config or language changes.

Notes

• This plugin is a relay only. It does not encrypt or decrypt message bodies.
• The client-side Krypt04Mcg implementation must keep the packet header format compatible with the reference PacketCodec.
• By default, the plugin rejects packets whose internal sender field does not match the player who sent the chat fragments.

License

This project is licensed under the The Unlicense. See LICENSE.

Optional public-key and file channels

The relay additionally registers krypt04mcg:public_key and krypt04mcg:file_share. Both use the existing wire layout: Minecraft UTF peer, UTF fragment, VarInt version (1). Each fragment contains transferUUID:index:total:data (zero-based index; at most 12,100 characters including header). The server replaces peer with the authenticated sender name. Only the public-key channel accepts receiver * to broadcast to other online subscribers. Files are always directed to one receiver. The relay forwards opaque encrypted file data; client settings default to disabling file sending and receiving.

Legacy chat, public-key and file channels enforce per-source ingress budgets of 256 packets/second (512 burst) and 2 MiB/second (4 MiB burst). Outgoing bytes are charged for every recipient, including broadcasts: 8 MiB/second per source (32 MiB burst) and 32 MiB/second globally (64 MiB burst). Excess traffic is dropped without delivery acknowledgements; retry transfers that do not complete. Normal file transfers paced at four chunks per client tick fit these budgets. Malformed UTF-8 and overflowing VarInts are rejected. Malformed-packet diagnostics use fine-level logging.

Binary data API channel (client 0.17.0; relay 1.6.0)

The relay registers krypt04mcg:data for incoming and outgoing plugin messages, and unregisters it with the other payload channels on reload or disable. Its wire format matches file_share, in this exact order:

1. peer: Minecraft writeUtf(peer, 16).
2. fragment: Minecraft writeUtf(fragment, 12100).
3. version: Minecraft writeVarInt(1); only version 1 is supported.

Strings use standard UTF-8 bytes prefixed by a VarInt byte length, not Java DataOutputStream.writeUTF. Both the UTF-16 character limit and the UTF-8 byte limit (three times the character limit) are checked. Truncation, invalid UTF-8, invalid/overflowing VarInts, trailing bytes and unsupported versions are rejected.

Client-to-server peer selects the destination player. Server-to-client peer is replaced with the real name of the authenticated sending connection; fragment and version are preserved. Only that online player, subscribed to krypt04mcg:data, receives the message. There is no broadcast (including *), chat fallback, or requirement to subscribe to chat/file channels. Data forwarding is independent of file-sharing settings.

The fragment is an opaque encrypted envelope fragment: the server does not add chat prefixes, validate file content, assemble fragments, encrypt/decrypt, or read application bytes. The business channel is inside the encrypted envelope and is distinct from the Minecraft payload channel. The client handles encryption, signatures, fragmentation, decryption and business-channel dispatch.

Data and tunnel traffic bypass the legacy packet/byte drop quotas in both directions, so client pacing and ordered stream delivery are not disrupted. They do not consume chat, public-key or file budgets. Payload size and wire validation still apply; only public keys can broadcast.

Resource limits

Chat fragments use a 1,024-entry inbox instead of scheduling a task per packet. Each server tick processes at most 64 incoming fragments and 64 outgoing sends, interleaving them and checking a shared 2 ms elapsed-time budget between operations (one decode or send may take longer). Completed messages are sent incrementally from an outbox capped at 64 messages, with a 10-second delivery deadline. Excess ingress and overflowing or expired deliveries are dropped. Disconnects remove affected deliveries; reload and disable empty both queues and cancel the processing task. Incomplete messages expire from their first fragment using a monotonic clock, even when traffic stops; duplicates do not refresh that deadline. When the pending-message capacity is full, new message IDs are ignored without evicting in-flight messages; existing messages can still complete. Completion, timeout, disconnect or reload releases capacity. Each player UUID is limited to 16 pending messages. There is no aggregate global, per-player, or completed-outbox buffered-text quota. Hexadecimal ID case aliases share one assembly. The configured global message limit still applies. Each decoded chat packet is limited to 256 KiB; fragment counts default to 2,048 and are clamped to 1–2,048. The timeout is clamped to 5–3,600 seconds. These collector limits cover vanilla chat/private commands; custom payload and raw streams use separate relay paths. More simultaneous large messages now retain more memory.

Existing config files retain their values. For large-packet support, set max-fragments-per-message: 2048 and keep the default 120-second assembly timeout, then reload the configuration or restart. Upgrade both clients to 0.29.0. When a message cannot finish using the configured chat pacing, the client uses an available chat custom-payload channel at one fragment per 50 ms; without the channel it fails before transmission. Receiver freshness/replay checks are unchanged. Raw API/file streams are unaffected.

Chat and legacy custom-payload transports each enforce aggregate ingress budgets of 2,048 packets/second (4,096 burst) and 8 MiB/second (16 MiB burst), as well as the per-source budgets above. Each transport also caps outgoing sends at 2,048/second per source (4,096 burst) and 8,192/second globally (16,384 burst), in addition to outgoing byte budgets. Public-key broadcast candidate scans have separate budgets with those same limits, including candidates that do not subscribe. Chat rejection warnings and related notifications are limited to once per second globally. Clients should retry incomplete messages after overload has subsided.

Missing custom language files fall back to English without interrupting reload. Language identifiers are limited to letters, digits and underscores after alias normalization; message placeholder values are inserted literally, without expanding embedded placeholders or & color codes.

Raw encrypted channels (raw_encrypted_channel client branch)

api-channel-count (default 16, clamped to 1..256) pre-registers krypt04mcg_stream:data/0 through krypt04mcg_stream:data/(n-1). An array maps each slot to one pair of players. Allocation selects a free slot subscribed to by both players; the server's pool is shared by all players. Each data channel has its own callback bound to a fixed array slot and cached channel name. Control messages update the routing array; data callbacks only read that slot, check the sender and direction, and forward the original bytes. They do not parse channel strings, query subscriptions, look up players/UUIDs/maps, or allocate envelopes. Subscription removal and disconnect events clear routes. Configure the client's apiChannelCount as well to make additional slots usable.

The relay uses the client's existing krypt04mcg_stream:control protocol for EXCHANGE, OPEN, ASSIGNED, READY, END, RESET and ABORT. Only control messages are decoded to establish and release routes; their sender comes from the authenticated player connection. No new protocol or data envelope is introduced. Data messages are passed directly as the original byte[] on the same channel, without payload length or content validation, encoding, decoding, encryption or decryption.

Data is forwarded only between the assigned players after READY and before that sender's END. Both ENDs, RESET, disconnect, lost subscription or 60 seconds of inactivity release the slot. Reload applies the configured count and aborts active streams. Raw data records bypass relay packet/byte rate quotas and are forwarded immediately in callback order, preserving client pacing and transport flow control. Bulk transfers do not consume the separate control-message ingress budget, so a download cannot exhaust the budget needed for END, RESET or opening another stream. Control-message floods retain the per-source and aggregate ingress limits described above. Server outbound buffering and server-wide network limits still apply, as with socket tunnels below.

Socket tunnel (Krypt04Mcg 0.22.0)

The relay advertises krypt04mcg:tunnel on registration, including after reload. The layout is Minecraft UTF peer (16 characters), VarInt envelope byte length, then up to 24 KiB of opaque binary envelope. There is no outer version field. The authenticated source name replaces peer; only the named online subscriber receives the unchanged envelope. Truncated, oversized or trailing data is rejected. No cryptography, stream counters or encrypted metadata are modified by the relay.

The tunnel has no relay drop-based rate quota or application retry queue. Bukkit forwards each accepted packet immediately in callback order. Client socket queues and the TCP transport provide flow control; Bukkit/server outbound buffering and server-wide packet limits still apply. This does not impose a bounded server queue or guarantee throughput under a slow receiver or server overload. Configure server network limits for expected traffic rather than silently discarding tunnel frames.