Krypt04Mcg (Aka: Krypt04Msg) means "Crypto for message (MineCraft message)".

The project was renamed from ObscuraLink-MC/ObscuraLink because "Obscura" is already used by a Minecraft modding organization. Krypt04Mcg is the chosen name to avoid that naming conflict.

Krypt04Mcg is an EXPERIMENTAL mod 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.

Krypt04Mcg is a Fabric or NeoForge client mod that transports post-quantum encrypted chat packets through ordinary Minecraft chat. It uses compact binary packets, Base64URL transport encoding, automatic fragmentation, TOFU public-key storage, and authenticated AEAD encryption.

• Client-side /k04m command tree, also available as /Krypt04Mcg:enc and /Krypt04Mcg:k04m.
• Configurable CMCE, HQC, NTRU Prime and ML-KEM key parameter sets, with X25519/X448 hybrid options.
• Bouncy Castle native composite ML-DSA signatures with EdDSA, ECDSA or RSA.
• Configurable Falcon and ML-DSA signature parameter sets.
• AES-256-GCM or ChaCha20-Poly1305 with a random 96-bit nonce per message.
• HKDF-SHA256 derives AEAD keys from KEM shared secrets.
• Optional signature verification for signed packets.
• Public-key import/export with Trust On First Use checks.
• Automatic chat fragmentation and out-of-order reassembly.
• Timeout cleanup and bounded receive caches.
• Optional Cloth AutoConfig-backed configuration.
• Local plaintext echo for outgoing encrypted chat, enabled by default, showing the sender, recipient, and message. Toggle showSentPlaintext ("Show Sent Plaintext") in the Cloth Config screen to show or hide message contents in send notifications. Applies to unsigned, signed, session, and group messages sent through commands or the chat panel; network messages remain encrypted.

This implementation targets:

• Minecraft Java 26.3
• Fabric Loader 0.19.5
• Fabric API 0.162.0+26.3
• Loom 1.18.2
• Gradle 9.8.0
• ModDevGradle 2.0.148
• JUnit 6.1.3
• NeoForge 26.3.0.52-beta (separate client build)
• Bouncy Castle 1.86
• Java 25

Dependency updates use the latest published stable versions compatible with Minecraft 26.3; snapshot, alpha, beta and release-candidate versions are excluded except for NeoForge.

The NeoForge build shares the protocol, cryptography, and storage code with Fabric. It requires no server installation for chat transport. Custom payload and public-key sharing still require a server relay that advertises the corresponding channels.

NeoForge's optional Cloth Config integration uses 26.3.159 for Minecraft 26.3 and detects its NeoForge mod ID, cloth_config. Install Cloth Config separately to enable saved settings and the config screen. The mod starts with default settings when Cloth Config is absent.

Use an installed Gradle 9.8.0 for these commands. CI installs the same stable version; Gradle Wrapper files are managed separately.

gradle build
gradle -p neoforge build

If you prefer a wrapper, generate one with a local Gradle install:

gradle wrapper
./gradlew build
./gradlew -p neoforge build

The Fabric and NeoForge builds each declare Java 25 in gradle/gradle-daemon-jvm.properties. Gradle uses these Daemon JVM criteria to run the build with Java 25 even when the launcher uses Java 21, as in GitHub's managed automatic dependency submission job. If no local Java 25 installation is available, Gradle downloads a stable Temurin 25 JDK from Adoptium for the configured Linux, macOS or Windows platform.

Encrypted chat packets can contain up to 256 KiB of complete binary packet data and 2,048 fragments. A maximum-size packet uses 1,942 fragments at the default 180-character payload. Smaller configured slices are enlarged when needed to fit the fragment count; every chat line still fits Minecraft's 256-character limit. A long custom prefix may reduce usable capacity.

If configured pacing would miss the fixed two-minute assembly window, the client uses an available chat custom-payload channel at one fragment per 50 ms. Without that channel, it fails before sending and reports that the relay needs updating or the message must be shortened. Queued waits and stalled sends also have deadlines; authenticated freshness and replay checks are retained. Upgrade both clients to 0.29.0 and the relay to 1.9.0; old clients cannot receive large four-digit fragment counts. Existing relay configs should set max-fragments-per-message to 2048. Relay aggregate/per-player/outbox text quotas are removed; packet size, message counts, fixed expiry and traffic budgets still apply. Raw stream API/file protocols are unchanged.

Current version: 0.29.0 for Fabric and NeoForge. See CHANGELOG.md for the new progress HUD, sender quotas, and upgrade notes in this release.

GitHub Actions builds the mod and publishes release artifacts automatically when a tag matching v* is pushed:

git tag -a v0.29.0 -m "Release 0.29.0"
git push origin v0.29.0

The release workflow can also be triggered manually from the Actions tab. Manual builds are published under generated snapshot-YYYYMMDD-HHMMSS tags.

Release artifacts include:

• the mod JAR from build/libs
• a detached .jar.sign signature for each release JAR
• public_key.pem for signature verification

To verify a downloaded release JAR:

openssl dgst -verify public_key.pem -signature krypt04mcg-0.29.0.jar.sign krypt04mcg-0.29.0.jar

Krypt04Mcg is licensed under the The Unlicense (Unlicense).

gradle runClient

Build the project, then copy build/libs/krypt04mcg-<version>.jar into the client mods directory together with Fabric API. Cloth Config is optional and enables saved settings and the ModMenu settings screen.

Ready-to-use configuration presets include the default suite, the smallest signature + KEM ciphertext suite (Compact), CMCE + Falcon, SLH-DSA, and a category 5 suite using BC's native hybrid KEM and signature implementations. Copy a preset to the instance's config/krypt04mcg.json; see the preset instructions before changing existing keys.

Krypt04Mcg stores data under:

config/krypt04mcg/accounts/<minecraft-uuid>/
  keys/
    private/local.json
    public/*.json
  export/
  sessions/
  cache/
  secrets/master.key

Private and public key material are stored separately and scoped to the active Minecraft account. Private keys, trust bindings, session secrets, and enabled conversation history are encrypted with AES-256-GCM. On Windows, the storage master key is protected with per-user DPAPI; other platforms use an explicitly owner-only master-key file. Sensitive writes are atomic and owner-only permissions are applied where the platform supports them. Public-key records include algorithm, owner, UUID, a full SHA-256 fingerprint, creation time, and Base64URL key data.

Group membership, sent ciphertext fragments, and decryption/replay history retain their existing JSON formats. Their files reject symbolic links in the path, including dangling links, and enforce owner-only access when read or written. Group and sent-fragment updates use private temporary files and atomic replacement where supported. If these files or their parent directories were previously linked, move their contents into regular local storage. /k04m key export writes your shareable public key JSON inside the active account's export directory.

The long-term KEM, ephemeral KEM, signature and AEAD configuration fields use dropdown menus on both Fabric and NeoForge.

The KEM and signature selections only apply when no local key exists or when a key is explicitly regenerated. Changing the configuration never rewrites an existing key. Encryption, signing, verification, and decryption resolve algorithms from key records and packet algorithm identifiers rather than assuming the current configuration.

Supported key selections are the eight ISO/IEC 18033-2 CMCE parameter sets already exposed by this mod (mceliece460896, mceliece6688128, mceliece6960119, and mceliece8192128, each with its f variant), HQC-128/192/256, all six parameter sets for each of NTRULPRIME and SNTRUPRIME, ML-KEM-512/768/1024, Falcon-512/1024, ML-DSA-44/65/87, all 24 SLH-DSA variants (the 12 SHA2/SHAKE parameter sets in both pure and pre-hash forms), all three SQIsign parameter sets (SQIsign-lvl1, SQIsign-lvl3, and SQIsign-lvl5), and all 44 SNOVA variants. SNOVA includes the base parameter sets 24-5-4, 24-5-5, 25-8-3, 29-6-5, 37-8-4, 37-17-2, 49-11-3, 56-25-2, 60-10-4, 66-15-3, and 75-33-2, each with SSK, ESK, SHAKE-SSK, and SHAKE-ESK variants (for example, SNOVA-24-5-4-SSK). The long-term defaults are ML-KEM-768+X25519, MLDSA65-Ed25519-SHA512, and AES-256-GCM. The independently configurable ephemeral KEM used only by /k04m exchange and /k04m etell sessions also defaults to ML-KEM-768+X25519.

Version 0.25.0 adds 52 hybrid KEM selections: every supported KEM parameter set can be paired with either X25519 or X448 (for example, HQC/hqc192+X448). These selections are available for both long-term keys and the independently configured ephemeral handshake key. ML-KEM-768+X25519 uses BC's native MLKEM768-X25519-SHA3-256 composite KEM; ML-KEM-1024+X448 uses BC's native MLKEM1024-X448-SHA3-256 composite KEM. All other pairings use BC's existing KEM and X25519/X448 implementations, combined by BC's HKDF-SHA256 over the PQ secret followed by the classical secret. The HKDF context binds a versioned domain label, the exact suite identifier, both encapsulations and both recipient public keys. No classical curve or post-quantum primitive is implemented by this mod. Invalid or missing components fail the operation; hybrid selections never fall back to a single component. The custom combinations are a mod-specific format, not X-Wing or a standard composite KEM.

The signature selector also offers all 18 BC native composite signature suites: ML-DSA-44 with Ed25519, ECDSA P-256 or RSA-2048; ML-DSA-65 with Ed25519, ECDSA P-256/P-384/brainpoolP256r1 or RSA-3072/4096; and ML-DSA-87 with Ed448, ECDSA P-384/P-521/brainpoolP384r1 or RSA-3072/4096. RSA choices include the PKCS#1 v1.5 and PSS variants exposed by BC (ML-DSA-87 uses PSS only). Signing, combination, key encoding and verification are delegated to BC; verification requires both signatures. Example selections are MLDSA44-Ed25519-SHA512 and MLDSA87-Ed448-SHAKE256.

Version 0.26.0 adds all 97 parameter selections exposed by BC 1.86 for these additional signatures:

Each selection also has +Ed25519 and +Ed448 hybrid variants, adding 194 hybrid choices. Examples include MAYO-1+Ed25519, HAETAE-3+Ed448, QR-UOV/qruov1q127L3v156m54+Ed25519 and SDITH-THRESHOLD-CAT5-P251+Ed448. BC provides the PQ and classical key generation, key decoding, signing and verification. These new pairings use a mod-specific versioned format; they are not BC's native ML-DSA composite suites and are not a standardized composite signature format. Both components sign the same length-framed transcript containing a versioned domain label, the exact suite identifier, the SHA-512 hash of both public keys and the SHA-512 hash of the message. Hashing is performed by BC. Verification requires both signatures; incomplete signatures, malformed framing and trailing bytes are rejected, with no fallback to a single component. The existing BC native ML-DSA composite signatures and the hybrid defaults remain unchanged.

Every supported PQ signature parameter selection now offers both +Ed25519 and +Ed448. This includes 152 additional pairings for Falcon (2 parameter sets), ML-DSA (3), SLH-DSA (24, including every pre-hash variant), SQIsign (3), and SNOVA (44). Examples are Falcon-512+Ed25519, ML-DSA-87+Ed448, SLH-DSA-SHAKE-256F-WITH-SHAKE256+Ed448, SQIsign-lvl3+Ed25519, and SNOVA-24-5-4-SSK+Ed448. These selections use the same mod-specific versioned signature framing and transcript binding described above, and require both signatures. They are available in the Fabric and NeoForge configuration dropdowns and work with saved identities and signed ephemeral handshakes. The explicit ML-DSA-65+Ed25519 selection uses this custom format; the existing MLDSA65-Ed25519-SHA512 default continues to use BC's native composite format. Both peers must support the selected identifier. To adopt a new long-term signature suite, regenerate the local keys and exchange the new public identity with contacts.

The new signature families are experimental, non-standardized selections. Large UOV public keys are supported by local import/export and the optional public-key sharing channel, whose bounded maximum is now 512 chunks (about 6 MB of JSON). This accommodates the largest UOV public key alongside the largest supported CMCE public key. Chat packet and fragment limits remain in force. Both peers need version 0.26.0 or newer for the new signature suites and larger public-key transfers.

Existing keys and explicit saved selections stay unchanged; new and missing selections default to the hybrid suites above. To use a long-term hybrid KEM or hybrid signature, select it in the configuration, explicitly regenerate your keys and exchange the new public keys with your contacts. An ephemeral hybrid selection takes effect on the next exchange without regenerating long-term keys. Both peers need version 0.25.0 or newer to use these suites; existing non-hybrid suites remain supported and the packet protocol version is unchanged.

Bouncy Castle 1.86 removes the round-3 CMCE implementation and the non-standardised CMCE/mceliece348864 and CMCE/mceliece348864f selections. Saved configurations using either removed selection fall back to ML-KEM-768. Existing round-3 CMCE keys cannot be decoded by 1.86, even for parameter sizes still supported by the ISO implementation. Back up the account storage before upgrading; CMCE users need to replace their local keys and exchange fresh public keys with their contacts. Existing ML-KEM keys remain usable.

/k04m tell <receiver> <message>
/k04m stell <receiver> <message>
/k04m exchange <receiver>
/k04m etell <receiver> <message>
/k04m gtell <group> <message>
/k04m group create <name> <members>
/k04m group list
/k04m group delete <name>
/k04m resend [messageId]
/k04m session list
/k04m session clear <player>
/k04m session refresh <player>
/k04m showalgs
/k04m status <player>
/k04m key [gui]
/k04m key list
/k04m key fingerprint <player>
/k04m key export
/k04m key import <player> <data-or-file>
/k04m key delete <player>
/k04m key remove <player>
/k04m key regenerate
/k04m key regenerate <current-kem-fingerprint>
/k04m key verify <player> <kem-fingerprint>:<signature-fingerprint>
/k04m key trust <player>
/k04m key distrust <player>

Open the key manager with /k04m key or /k04m key gui on Fabric and NeoForge. You can also assign the Open Key Manager binding in Controls (unbound by default). The left pane lists your identity and imported players with trust indicators; the right pane shows their stored algorithms and copyable fingerprints. Scroll either pane when needed. Import accepts a public key file path, JSON or Base64URL. Export writes only your public keys and copies the file path. Verify requires both fingerprints from a trusted channel; Delete confirms removal of the imported identity, trust record and saved chat session. Regenerate requires your current KEM fingerprint and uses the algorithms selected in configuration.

/k04m status <player> shows that player's long-term KEM and signature algorithms from their stored public keys, or unknown when no public key is available. The separately labeled local configuration describes your own settings. The public key export does not include the other player's ephemeral KEM or AEAD configuration; stored keys do not report subsequent remote key changes automatically.

Import flow:

1. The other player runs /k04m key export.
2. They send you the exported JSON file through a trusted side channel and tell you the printed fingerprints.
3. You run /k04m key import <player> <file-or-json>.
4. First import is trusted automatically. If a key changes later, Krypt04Mcg refuses to overwrite it silently. Use /k04m key delete <player> (alias: /k04m key remove <player>) to remove that player's imported public keys, trust record, and saved session before importing a replacement. Player names are case-insensitive; your own keys cannot be deleted this way. A replacement starts with TOFU trust and must be verified again.
5. To mark the identity VERIFIED, compare both full fingerprints out of band and pass their colon-separated pair to /k04m key verify.

Regeneration flow:

1. Select the replacement KEM and signature parameter sets in the mod configuration.
2. Run /k04m key regenerate; the mod prints the current KEM fingerprint and the exact confirmation command.
3. Run /k04m key regenerate <current-kem-fingerprint> to replace both local key pairs.
4. Export and redistribute the new public key. Existing peers will reject it as a TOFU key change until they deliberately replace the old key.

Packets are compact binary and then Base64URL encoded for chat transport. The binary packet layout is:

u8   protocolVersion
u8   packetType
u8   flags
u16  senderLength
bytes senderUtf8
u16  receiverLength
bytes receiverUtf8
i64  timestampMillis
 16   messageId
 [u16 kemAlgorithmLength + bytes kemAlgorithmUtf8]
 [u16 signatureAlgorithmLength + bytes signatureAlgorithmUtf8]
u16  aeadAlgorithmLength
bytes aeadAlgorithmUtf8
u16  hkdfAlgorithmLength
bytes hkdfAlgorithmUtf8
u16  nonceLength
bytes nonce
i32  kemCiphertextLength
bytes kemCiphertext
i32  ciphertextLength
bytes ciphertext
i32  signatureLength
bytes signature

Protocol v4 adds u16 sessionIdLength + bytes sessionIdUtf8 and i64 sequence immediately after message ID for SESSION_MESSAGE only, and omits its signature length/data entirely. SESSION_EXCHANGE retains its PQ signature. Other packet layouts remain as in v3; v1–v3 decoding is retained for non-session messages.

The bracketed v3 fields are conditional: KEM identifiers are omitted from session messages, and signature identifiers are omitted from unsigned messages. Protocol v3 also removes the obsolete packet-level fragment index/total fields. The decoder retains the original v1/v2 layout and AAD rules for compatibility.

Packet types:

• 1: KEM encrypted message.
• 2: signed KEM encrypted message.
• 3: session exchange.
• 4: session message.

• AES/ECB is not used.
• The packet-selected supported AEAD is used with a fresh random nonce per encrypted message.
• SecureRandom generates message IDs, nonces, KEM randomness, and session material.
• KEM shared secrets are never used directly as AEAD keys.
• HKDF-SHA256 derives AEAD keys with the message ID as salt.
• Protocol v3 AEAD AAD covers protocol version, packet type, flags, sender, receiver, timestamp, message ID, and all present algorithm identifiers. Timestamp tampering therefore fails even for unsigned packets.
• Incoming packets select their supported algorithms from the authenticated protocol identifiers; the KEM and signature identifiers must match the corresponding stored key records.
• Signatures cover AAD plus timestamp, nonce, KEM encapsulation, and ciphertext.
• Decryption rejects wrong receivers before attempting plaintext display.
• The authenticated packet sender must match the outer Minecraft sender; transports without an authenticated sender accept signed packets or AEAD-authenticated messages from an established, identity-bound session.
• DISTRUSTED identities are rejected before decryption or session state changes. Verified trust records bind the player name and both public-key fingerprints.
• Accepted timestamps have a bounded freshness window, replay records are retained per sender, and session messages authenticate the session epoch and a monotonic sequence number before counters advance.
• Decryption failures do not display garbage plaintext.
• Signature failures are displayed explicitly as invalid.

Each chat fragment has this form:

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

The receiver supports out-of-order fragments, ignores duplicates and expires assemblies two minutes after their first fragment. Network receive admission is bounded to 128 pending messages globally and 16 per transport sender, ignoring name case; unbound shadow chat shares one bucket. New IDs cannot evict admitted messages. Hex ID case aliases share an assembly. Disconnect/join and saved settings clear pending transfers.

Krypt04Mcg remains a client-side mod. Servers do not need to install any plugin or mod for the default chat transport, and the optional payload channel is not used for mandatory login or configuration negotiation.

If a server plugin wants to relay fragments without normal chat, it can declare support for this play-stage custom payload channel:

channel id: krypt04mcg:chat_fragment
direction C2S: client -> server
payload fields C2S:
  string receiver
  string fragment
  varint version
direction S2C: server -> client
payload fields S2C:
  string sender
  string fragment
  varint version

The first field is direction-specific. For C2S it is the intended receiver. For S2C it is the authenticated Minecraft sender. The server must derive the S2C sender from the player connection that supplied the C2S payload; it must not accept a sender name supplied by a client or copy the C2S receiver into that field.

Client send mode CUSTOM_PAYLOAD only sends on this channel when Fabric reports the connected server can receive krypt04mcg:chat_fragment; otherwise the client simply skips payload sending and does not require server-side support.

/k04m exchange is a signed two-message handshake using the dedicated SESSION_EXCHANGE packet type. The initiator creates an in-memory one-time KEM key pair (ML-KEM-768+X25519 by default); the responder encrypts fresh session material only to that temporary public key and binds both identities, UUIDs, both fingerprint pairs, the session ID, and the request message ID into the exchange transcript. The initiator destroys the temporary private key after accepting the response or after a short timeout. Consequently, later compromise of either long-term KEM private key does not decrypt a recorded exchange response.

/k04m etell uses the resulting session secret with an AEAD-only SESSION_MESSAGE packet (no per-message PQ signature or additional HMAC). Protocol v4 carries the session ID and monotonic sequence in the packet header and authenticates them, together with sender and receiver, through AEAD AAD. The encrypted payload contains only its version and message. Old v1–v3 session messages are rejected; both peers must upgrade. tell and stell continue to use their existing long-term recipient KEM path and do not use the ephemeral KEM setting.

The encrypted chat panel can be opened with the configured Krypt04Mcg key binding. It lists imported players, recent peers, and configured groups. Group targets are shown with a # prefix and send through the existing group fan-out flow.

Sending and receiving encrypted chat/session/exchange fragments now show progress bars at the upper right, both in the game HUD and in this panel. Each bar shows the peer, percentage, fragment counts and transfer state; up to two bars per direction are visible. showProgress and showReceiveProgress independently control display, and hiding the HUD also hides the bars. Results remain for up to three seconds, with active transfers prioritized.

Send counts advance only after local transport submission succeeds; the final state is not a remote delivery receipt. Receive completion follows decryption, freshness and replay/session validation, rather than only assembling bytes. Missing custom-payload support now fails instead of silently appearing sent. The local plaintext notification/history still represents an accepted, queued message. Bars do not track raw API or file-stream bytes. See the progress and sender-quota audit.

Recent plaintext conversation history is cached locally under:

config/krypt04mcg/accounts/<minecraft-uuid>/cache/conversations.json

The encrypted cache is bounded to the most recent 300 entries and is disabled by default. It can be enabled with the enableConversationHistory config option. With this option disabled, the GUI still displays up to 300 live conversation entries in memory, without loading or saving conversation history on disk.