Skip to content

Home

Jump to bottom
Jinnang233 edited this page Oct 4, 2026 · 9 revisions

Krypt04Mcg Wiki

本 Wiki 按 Krypt04Mcg 0.23.2 的 main 源码重新整理，更新于 2026-10-05。内容以当前源码、gradle.properties、README.md、SECURITY_REVIEW.md、配置、命令和公开 API 实现为准；若 README 与源码有冲突，以源码为准。

Warning

Krypt04Mcg 是实验性项目，不是经过独立安全审计的成熟通信工具。 项目大量使用 AI 辅助开发，协议、密码学封装、密钥存储、网络行为、跨 Loader 兼容和依赖配置都可能仍有缺陷。不要用它保护敏感、重要、生产、监管或高价值数据。

Krypt04Mcg 是什么

Krypt04Mcg（Krypt04Msg，意为 “Crypto for Minecraft message”）同时提供 Fabric 与 NeoForge 客户端构建。核心协议、密码学和本地存储代码共享；普通 CHAT / SERVER_COMMAND 聊天传输不要求服务器安装 Mod。

当前版本主要提供：

  • 普通 KEM 加密消息：/k04m tell
  • 带后量子数字签名的 KEM 加密消息：/k04m stell
  • 临时 KEM 会话交换：/k04m exchange
  • 会话内 AEAD 消息：/k04m etell
  • 本地群组与逐成员加密发送：/k04m gtell
  • 公钥导入、导出、TOFU、人工指纹验证和不信任标记
  • 自动聊天分片、乱序重组、重复片段处理、超时清理和重放检测
  • CHAT、SERVER_COMMAND、CUSTOM_PAYLOAD 三种聊天传输模式
  • 可选加密聊天 GUI，默认按 K 打开
  • 可选本地会话历史
  • CUSTOM_PAYLOAD 下的在线公钥分享
  • 通过 Raw encrypted channel API / KryptSocket 的加密文件传输
  • 给其他客户端 Mod 使用的 KryptSession、KryptSocket、send / receiver API

Important

0.23.2 的 Mod API 与旧 0.18/0.19 Wiki 不兼容。 旧 DataTransfer、TransferResult、DATA/ACK/NACK envelope、重传/完成回执，以及 krypt04mcg:data、krypt04mcg:file_share 通道已经移除。当前实现改为控制通道 + 预注册原始数据槽。

当前目标环境

组件 当前配置
Krypt04Mcg 0.23.2
Minecraft Java 26.3
Fabric Loader 0.19.5
Fabric API 0.161.0+26.3
NeoForge 26.3.0.16-beta
Java 25
Fabric Loom 1.17.20
Gradle 9.5.1（CI / wrapper 目标）
Bouncy Castle 1.85.2
Cloth Config 26.3.159
Mod Menu 21.0.0

Fabric 与 NeoForge 的 Cloth Config 都是可选集成；没有 Cloth Config 时 Mod 仍能启动。Fabric 侧还可配合 Mod Menu 打开设置界面。

最短聊天使用流程

假设 Alice 和 Bob 都安装了 Krypt04Mcg：

  1. 双方第一次启动后生成自己的长期 KEM 和签名密钥。
  2. Alice 执行 /k04m key export，Bob 也执行一次。
  3. 双方通过可信侧信道交换导出的公钥 JSON 和完整指纹。
  4. Alice 执行 /k04m key import Bob <文件路径>；Bob 对 Alice 做同样操作。
  5. 双方比较完整的 KEM指纹:签名指纹，再执行：
/k04m key verify Bob <kem-fingerprint>:<signature-fingerprint>
  1. 发送带签名的加密消息：
/k04m stell Bob 你好，这是加密消息
  1. 如果希望建立聊天 Session：
/k04m exchange Bob
/k04m etell Bob 这条消息走会话密钥

也可以按 K 打开加密聊天面板。

聊天消息的四种核心路径

操作 加密方式 每条消息签名 典型用途
tell 对接收方长期 KEM 加密 否 有可信 transport sender 时的简单加密
stell 对接收方长期 KEM 加密 是 端到端发送者认证
exchange 签名握手 + 一次性临时 KEM 是 建立认证聊天会话
etell Session secret + AEAD + 序号 否 已建立聊天会话后的连续消息

etell 不为每条消息重新做后量子签名；身份来自已签名的会话交换，后续由 AEAD、sessionId 和单调序号保护。

0.23.2：Raw encrypted channel API

当前公开 Mod API 不再使用“可靠 transfer + ACK/NACK + 再在上面套 Stream”的多层设计，而是直接把 Minecraft 的可靠、有序 Custom Payload 作为 AEAD record transport。

服务器端需要转发：

krypt04mcg_stream:control
krypt04mcg_stream:data/0 ... krypt04mcg_stream:data/(n-1)

其中 n = apiChannelCount，默认 16，范围 1..256，修改后需要重启客户端。

  • control：会话交换、slot 分配、READY、认证 EOF / RESET，以及 Relay 的 ABORT。
  • data/N：只有 XChaCha20-Poly1305 ciphertext || 16-byte tag，没有应用头、stream ID、sequence、nonce、Base64、JSON 或 ACK。
  • 单条 record 最多承载 16 KiB 明文。
  • 每个 KryptSocket 每个方向最多缓冲 1 MiB。
  • 活动流数量不能超过预注册 slot 数。
  • 打开、分配或空闲超过约 60 秒会失败。
  • send(...) 是 convenience one-shot stream，返回 void，最多一次排入 1 MiB；没有远端送达/持久化回执。

API 的 Session 存储在账号目录下独立的 stream-api 区域，不再与聊天 /exchange Session 共用状态。详细线程规则、半关闭语义和 Relay 合约见 Mod API。

文件发送也已经迁移到同一套 KryptSocket 流，应用 channel 为：

krypt04mcg_file:stream

旧 krypt04mcg:file_share 已移除；在线公钥分享仍使用 krypt04mcg:public_key。

它保护什么，不保护什么

Krypt04Mcg 的目标是让 Minecraft 传输层不直接承载应用明文，并检查篡改、错误接收方、部分重放和密钥替换等情况。但它 不隐藏通信元数据：服务器通常仍能知道通信双方、时间、数据量和使用的 payload 通道；旁观者在聊天模式下还可能看到密文片段。

它也无法防止：

  • Minecraft 客户端、Java 进程或操作系统本身已被攻陷
  • 恶意服务器阻断、丢弃、限速、重排或延迟通信
  • 首次公钥交换被中间人替换且用户没有人工核对指纹
  • Mod、Relay、依赖或密码协议实现中的未知漏洞
  • 通过长度、时序、频率进行流量分析
  • 上层 API 使用者自己造成的 framing、持久化、幂等或事务一致性问题

因此它更适合作为 实验性 Mod / 密码协议练习 / Mod 间安全传输实验，而不是现实中的高安全通信工具。

Wiki 导航

相关源码入口

如果要审查当前实现，建议优先看：

  • CryptoService：KEM、签名、聊天 AEAD、HKDF 和密钥校验
  • PacketCodec：聊天 / Session 协议二进制格式、AAD、签名输入
  • FragmentService / FragmentReassembler：聊天分片与重组
  • SessionHandshakeService / SessionService：认证会话交换和会话状态
  • KeyStoreService / KeyTrustService：公钥与信任关系
  • SensitiveFileStore：本地敏感数据加密
  • DataTransferService：0.23.2 raw stream 的连接、slot、生命周期与调度
  • ChannelCrypto：stream HKDF、XChaCha20-Poly1305、控制消息认证
  • RawChannelPayload / ControlPayload：当前 Relay wire contract
  • Krypt04McgApi / KryptSession / KryptSocket：公开 Mod API
  • FileStreamCodec / OptionalSharing：当前文件流与用户确认流程
  • Fabric 与 NeoForge 各自的 Krypt04McgMod：Loader 集成与 payload 注册

Krypt04Mcg

Wiki 基线：0.23.2 更新：2026-10-05

Clone this wiki locally