Release v3.3
最终审查中

下一代安全通信系统

多层加密架构,从传输层到应用层纵深防御;混合后量子密钥协商,为未来的量子威胁做好准备; 纯标准库实现,零第三方加密依赖,可审计、可自部署、可验证。

7000+Python 代码行数
23核心功能模块
4加密层级
3密钥协商模式
2客户端形态
4协议回退层级
🔒

多层纵深加密

传输层 X25519 + ML-KEM-768 混合密钥协商,应用层 Signal Protocol (X3DH + Double Ratchet) 端到端加密。每层独立密钥,任一环节被攻破不影响整体安全。即使服务器完全沦陷,攻击者也只能拿到无法解密的随机字节。

后量子安全 (PQC)

ML-KEM-768 (Kyber-768, NIST FIPS 203) 与 X25519 混合,NIST Level 3 后量子安全级别。只要经典 ECC 或后量子 KEM 任一算法未被破解,通信即安全。为量子计算机时代的到来提前做好准备。

💻

Windows 双客户端

GUI 图形界面 (tkinter 主题) + CLI 命令行,两种形态满足不同场景。GUI 支持自定义背景、emoji 面板、动态日志栏、文件收发;CLI 轻量高效,适合服务器环境和自动化脚本。

Cloudflare Tunnel 原生集成

基于标准 HTTP/WebSocket (RFC 6455),直连 wss:// 域名,无需本地端口映射,无需客户端安装 cloudflared。服务端同一端口同时挂载 WS 和 HTTP API,按 Upgrade 头自动分发。

📦

纯标准库 + libsodium

仅依赖 Python 标准库 + libsodium(ISC 许可证)。核心密码学运算 (X25519/Ed25519/ChaCha20-Poly1305) 下沉到原生库 FFI 调用,常量时间执行,无时序侧信道,规避供应链攻击风险。

🛡

隐私合规设计

口令从不明文落盘 (PBKDF2 200,000 次迭代),加密日志依法保留 185 天。注册前必须完成隐私政策、跨境传输告知、账号注销协议的三重同意。账号注销后物理删除全部用户数据。

设计哲学:不做"又一个聊天软件",而是提供一套可审计、可自部署、可验证的安全通信基础设施。 服务端与客户端源码完全开放,密码学协议基于公开标准(RFC 7748/8032/6455/3526,NIST FIPS 203), 每一步密钥派生都可独立验证。服务端仅需 Python 3.8+ 和 libsodium,四个文件即可运行。

系统架构全景

E-Chat 采用经典的分层架构,每一层解决一个独立的安全问题,层与层之间通过明确定义的接口通信:
网络层 (ws_layer.py):负责 WebSocket 连接的建立、维护、心跳、重连。实现 RFC 6455 完整的帧协议 (文本帧/二进制帧/ping-pong/close),支持 TLS 指纹伪装与域前置。
安全层 (sec_toolkit.py + native_crypto.py):负责所有密码学运算——密钥协商、会话加密、口令派生、加密日志。native_crypto.py 通过 ctypes FFI 调用 libsodium,sec_toolkit.py 提供纯 Python 的 ML-KEM-768 实现和协议编排。
协议层 (signal_protocol.py + e2ee_client.py):负责 Signal Protocol 的完整实现——X3DH 协商、Double Ratchet 状态管理、prekey 生命周期。
应用层 (chat_server.py / chat_client.py / gui_client.py):负责聊天业务逻辑——消息路由、文件传输、群组管理、用户管理、离线缓存。
治理层 (consent_manager.py):负责隐私合规——三重同意机制、日志留存策略、账号注销流程。

威胁模型

网络窃听者:被动监听公网链路,试图获取通信内容。对策:TLS 1.3 + 混合密钥协商 + AEAD 加密。
主动中间人:拦截并篡改通信流量。对策:挑战-响应鉴权 + HMAC 完整性校验 + 公钥绑定。
服务端入侵者:获得服务器完全控制权。对策:E2EE 端到端加密,服务端仅存密文和公钥。
数据库泄露:用户数据库被拖库。对策:口令仅存 PBKDF2 派生值,无明文存储。
量子攻击者:Harvest Now, Decrypt Later (HNDL)。对策:X25519 + ML-KEM-768 混合,后量子安全。
DPI 审查者:基于流量特征识别和封锁。对策:流量填充 + TLS 指纹伪装 + 域前置 + 多协议降级。

技术选型理由

Python 而非 Rust/Go:Python 标准库自带 asyncio、hashlib、hmac、secrets、json——无需任何第三方加密库即可构建完整的安全通信栈。教学和审计场景下,Python 的代码可读性远优于系统语言。
libsodium 而非 PyCryptodome:libsodium 是 NaCl 的便携式分支,由知名密码学家 Daniel J. Bernstein 等人设计,API 设计原则是"默认安全"——不给开发者犯错的机会。ISC 许可证,商业友好。
WebSocket 而非 gRPC/QUIC:WebSocket 是 HTTP/1.1 的升级协议,与 Cloudflare CDN 兼容性最好,无需额外协议支持。对于聊天这种低吞吐、长连接场景,WebSocket 足够。

发送方
X3DH 协商
Double Ratchet
ChaCha20-Poly1305
X25519+ML-KEM
WebSocket/HTTPS
Cloudflare Tunnel
接收方
当前状态:E-Chat v3.3 正在完成最后的代码审查与安全审计工作。审查内容包括:所有密码学原语的正确性验证、 端到端流程的完整自检、libsodium FFI 边界的安全性检查、以及 ML-KEM-768 纯 Python 实现的数学一致性验证。 审查通过后将正式发布。在此期间,欢迎通过下方联系方式与开发者交流。

安全架构:四层纵深防御

E-Chat 采用四层独立加密体系,每层密钥独立派生,构建从网络链路到应用消息的完整防护链。不存在"万能钥匙"——任何单层被攻破,其余层仍保护通信安全。

1

网络传输层 — TLS 1.3 / WSS

WebSocket over TLS (wss://),Cloudflare 边缘节点提供 TLS 终结,公网链路全程加密。客户端支持 TLS 指纹伪装 (JA3/JA4 对抗),通过自定义密码套件顺序模拟 Chrome 浏览器指纹,规避基于 TLS 指纹的 DPI 识别与封锁。

wss://TLS 1.3JA3/JA4 伪装域前置
2

会话协商层 — 混合密钥协商 + HKDF

每条连接独立完成 X25519 + ML-KEM-768 混合密钥协商。X25519 (Curve25519) 提供 128-bit 经典安全强度,ML-KEM-768 (Kyber-768) 提供 NIST Level 3 后量子安全。两者共享秘密 S1 || S2 拼接后经 HKDF-SHA256 派生 256-bit 会话密钥。具备完善前向保密 (PFS)——即使长期私钥泄露,历史会话密钥也无法恢复。

X25519ML-KEM-768HKDF-SHA256PFS256-bit key
3

身份鉴权层 — 挑战-响应零知识证明

口令从不明文传输,永不出本地。客户端本地执行 PBKDF2-HMAC-SHA256 (200,000 次迭代,salt 随机) 派生 verifier,登录时发送 HMAC(verifier, nonce_s || nonce_c || pub_c || pub_s) 作为证明。服务端仅存 salt + verifier 哈希,即使数据库完全泄露,攻击者也只能获得 PBKDF2 派生值,无法还原原始口令。结合 X25519 公钥绑定,防止跨会话重放攻击。

PBKDF2200K iterationsHMAC-SHA256挑战-响应防重放
4

应用消息层 — Signal Protocol 端到端加密

聊天消息走完整的 Signal Protocol 协议栈:X3DH 异步密钥协商 + Double Ratchet 双棘轮推进。底层 AEAD 加密由 libsodium 的 ChaCha20-Poly1305 实现。每条消息使用独立 256-bit 消息密钥,用后即销毁。提供前向安全 (PFS) 与后向安全 (PCS)。服务端仅转发密文,无法解密消息内容——即使执法机关要求提供数据,也只能交出随机字节。

X3DHDouble RatchetChaCha20-Poly1305libsodiumPFS + PCS
纵深防御原则:每层密钥独立派生,不存在"万能钥匙"。传输层 TLS 保护网络链路,会话层混合协商保护连接,鉴权层证明身份,应用层 E2EE 保护消息内容。即使传输层会话密钥泄露,应用层 E2EE 密钥仍保护消息;即使服务端被完全攻破,也只能获得无法解密的随机字节。口令在服务端仅存 PBKDF2 派生的验证字,即使数据库泄露也无法还原原始口令。

防攻击措施

登录防暴力破解

连续 10 次失败锁定 2 分钟。WS 和 HTTP 双通道共享同一计数器,无法通过换通道绕过。管理员可远程 lock/unlock 用户。

流量填充与随机化

所有消息统一填充到 1024 字节整数倍,心跳间隔随机化 (20-45 秒),心跳包大小随机化,防止基于流量模式的 DPI 分析与行为指纹识别。

安全内存清零

libsodium 提供 sodium_memzero / sodium_mlock 等安全内存操作,密钥使用后立即从内存中安全擦除,防止冷启动攻击与内存转储泄露。

密钥派生体系 (Key Derivation Hierarchy)

E-Chat 的密钥派生严格遵循"一钥一用"原则,从用户口令出发,通过层层 HKDF 派生,确保每个加密上下文使用独立密钥:
用户口令 → PBKDF2-SHA256 (200,000 iterations, 32-byte salt) → verifier (256-bit,仅存服务端,不可逆推口令)
混合共享秘密 (S1||S2, 64 bytes) → HKDF-SHA256 (salt=random, info="echat-v3.3-session-key") → 会话密钥 (256-bit)
会话密钥 → HKDF-SHA256 (info="echat-v3.3-conf") → 加密密钥 (256-bit) + HMAC 密钥 (256-bit),分别用于 AES-256-GCM / ChaCha20-Poly1305 和消息认证
X3DH 根密钥 → HKDF 迭代 → Chain Key → HMAC-SHA256 → Message Key (256-bit, 每条消息独立,用后即销毁)
服务端主密钥 (32 bytes, /opt/echat/server.key, chmod 600) → 用于加密日志 (seal) 和离线消息二次加密。 所有派生路径均为单向——从子密钥无法反推父密钥,从 verifier 无法反推口令。

端到端加密:Signal Protocol 完整实现

E-Chat 完整实现了 Signal Protocol 的核心协议栈 (X3DH + Double Ratchet),确保服务端"零知识"——只能转发密文,无法解密内容。这是目前学术界和工业界公认最成熟的异步端到端加密协议。详见 X3DH 规范Double Ratchet 规范

1

身份密钥 (IK) — Ed25519 长期签名密钥对

每个用户生成一对 Ed25519 密钥作为长期身份。私钥用于签名中期预密钥 (SPK),建立信任根。公钥随 prekey bundle 上传到服务端,供其他用户发起 X3DH 协商时使用。基于 libsodium 的 Ed25519 实现,128-bit 安全强度,签名 64 字节。

Ed25519libsodium64-byte sig
2

Prekey Bundle — 公钥包上传与分发

用户登录后自动生成并上传公钥包到服务端:1 个身份公钥 (IK)、1 个签名中期预密钥 (SPK + 签名)、20 个一次性预密钥 (OPK)。发送方通过 get_prekey 拉取接收方公钥包,消耗一个 OPK。OPK 耗尽后自动补发。服务端仅存储公钥,无法获取对应私钥。

IKSPK + SigOPK x20自动补发
3

X3DH — 三次椭圆曲线 DH 异步协商

发送方生成临时密钥对 (EK),拉取接收方公钥包后执行三次 X25519 密钥交换:
DH1 = EK_A * IK_B(发送方临时 + 接收方身份)
DH2 = IK_A * SPK_B(发送方身份 + 接收方中期)
DH3 = EK_A * SPK_B(发送方临时 + 接收方中期)
如有 OPK 则额外执行 DH4 = EK_A * OPK_B。所有结果拼接后经 HKDF 派生根密钥 (Root Key)。支持完全异步——接收方无需在线即可完成协商。

X3DHX25519 x3/x4HKDF异步协商
4

Double Ratchet — 双棘轮持续推进

DH Ratchet (DH 棘轮):每次收到对方新公钥时,执行一次新的 DH 计算,更新 Root Key 和 Sending Chain Key。Symmetric Ratchet (对称棘轮):每条消息从 Chain Key 派生独立的消息密钥 (Message Key),用后立即销毁,Chain Key 向前推进。前向安全 (PFS):历史消息密钥无法从当前状态恢复。后向安全 (PCS):密钥泄露后,新 DH 协商使后续消息恢复安全。

DH RatchetSymmetric RatchetPFSPCS
5

消息加密 — ChaCha20-Poly1305 AEAD

每条消息使用独立的 256-bit 消息密钥,经 ChaCha20-Poly1305 AEAD (Authenticated Encryption with Associated Data) 加密。Poly1305 提供 128-bit 消息认证码 (MAC),检测任何篡改;ChaCha20 提供 256-bit 流加密,防窃听。全部由 libsodium 原生 C 实现,常量时间执行,无时序侧信道,抗缓存攻击。

ChaCha20Poly1305AEADlibsodium256-bit key
服务端视角:服务端收到的每一条消息都是 {"kind":"e2ee_msg","from":"alice","to":"bob","payload":"<256 bytes random>","ik_x":"...","opk_pub":"..."}。 服务端按 to 字段转发,但无法解密 payload 的内容。即使执法机关要求提供数据,也只能交出不可解密的随机字节。 这从根本上杜绝了"服务端被入侵导致消息泄露"的风险。

Double Ratchet 安全属性

属性说明
前向安全 (PFS)历史消息密钥无法从当前状态推导
后向安全 (PCS)密钥泄露后新消息恢复安全
每条消息独立密钥Message Key 用后即销毁
抗乱序DH Ratchet 可跳过丢失的消息
异步支持接收方离线时发送方可继续推进

离线 E2EE 消息流程

1. 发送方在本地完成 E2EE 加密,得到密文 payload
2. 密文通过传输层加密通道发送到服务端
3. 服务端发现接收方离线,用主密钥二次加密后缓存到 offline.enc
4. 接收方上线后,服务端推送离线密文
5. 接收方在本地完成 E2EE 解密,获得明文
6. 服务端在整个链路中始终无法看到明文

棘轮状态管理与会话持久化

Double Ratchet 的核心挑战在于状态同步——通信双方必须维护完全一致的棘轮状态,否则后续消息将无法解密。E-Chat 的解决策略:
状态持久化:每个会话的 Ratchet State (Root Key, Sending Chain Key, Receiving Chain Key, DH Key Pair, 消息序号 Ns/Nr, 已跳过消息密钥缓存) 序列化为 JSON,写入本地文件。客户端重启后自动恢复状态,无需重新协商。
乱序处理:网络延迟可能导致消息到达顺序与发送顺序不一致。接收方维护一个 skipped message key cache (MKSKIPPED),以 (DH公钥, 消息序号) 为键缓存已跳过但未使用的消息密钥。当乱序消息到达时,从缓存中查找对应密钥,而非丢弃消息。
会话唯一标识:每个 E2EE 会话由 (Alice IK, Bob IK) 唯一标识。同一对用户之间只有一个活跃会话,但 Alice 和 Bob 各自维护独立的发送链和接收链。
Prekey 耗尽处理:当接收方 OPK 耗尽时,发送方使用最后一个 OPK 的序号 (或仅使用 SPK) 完成 X3DH。这不是安全漏洞——X3DH 的设计允许 OPK 为可选,仅提供额外的后向安全。

后量子安全:X25519 + ML-KEM-768 混合方案

量子计算机对 RSA、ECC 等传统公钥密码构成根本性威胁。Shor 算法可在多项式时间内破解所有基于离散对数和大数分解的密码体制。E-Chat 采用 NIST 后量子密码标准化 选定的 ML-KEM-768 与经典 ECC 混合方案,确保"现在安全,未来也安全"。

为什么选择混合方案而非纯后量子?

密码学社区的共识是:当前阶段不要单独依赖后量子算法。原因有三:
1. ML-KEM-768 (Kyber) 虽经 NIST 多年标准化审查 (2017-2024),但作为相对较新的格基密码体制,其长期安全性尚未经过与 ECC 同等时间 (近 20 年) 的考验;
2. 格基密码的参数选择依赖对格归约算法进展的持续评估,存在参数被未来攻击削弱的理论风险;
3. 混合方案 (Hybrid) 将 X25519 和 ML-KEM-768 的共享秘密拼接,只要任意一个算法未被攻破,整体通信就安全。这是目前最保守也最可靠的后量子迁移策略。

算法类型安全级别公钥大小密文大小共享秘密标准化
X25519ECDH (Curve25519)128-bit 经典32 bytes32 bytes32 bytesRFC 7748
ML-KEM-768格基 KEM (Kyber-768)NIST Level 31,184 bytes1,088 bytes32 bytesFIPS 203
Hybrid (本项目)X25519 + ML-KEM-768经典 + 后量子 双重1,216 bytes1,120 bytes64 bytesE-Chat 实现
DH-2048 (兼容)FFDH (MODP Group 14)~103-bit 经典256 bytes256 bytes256 bytesRFC 3526
混合协商详细流程:
1. 客户端生成 X25519 临时密钥对 + ML-KEM-768 密钥对,在 hello 消息中声明 kex="hybrid",发送 X25519 公钥和 ML-KEM-768 公钥。
2. 服务端收到后,执行 X25519 DH 计算共享秘密 S1,再执行 ML-KEM-768 封装 (Encaps) 生成共享秘密 S2 和密文 CT。
3. 将 S1 || S2 (64 bytes) 拼接后经 HKDF-SHA256 派生最终 256-bit 会话密钥。
4. 服务端返回 hello_ack,包含 X25519 公钥和 ML-KEM-768 密文。
5. 客户端用 ML-KEM-768 私钥解封装 (Decaps) 获得 S2,与本地计算的 S1 拼接,同样经 HKDF 得到相同会话密钥。
6. 会话密钥的第一条使用即为鉴权 proof 的加密传输——如果双方密钥不一致,后续 HMAC 验证自动失败,无需额外密钥确认步骤。

ML-KEM-768 技术参数

模块秩 (k)3
多项式次数 (n)256
模数 (q)3,329
噪声参数 (η1,η2)2, 2
公钥大小1,184 bytes
私钥大小2,400 bytes
密文大小1,088 bytes
安全级别NIST Level 3 (AES-192 等效)

实现细节

X25519、Ed25519、ChaCha20-Poly1305、HMAC-SHA256 通过 native_crypto.py FFI 调用 libsodium 原生 C 实现,获得常量时间执行与安全内存处理。

ML-KEM-768 保留纯 Python 数学定义直接计算实现,避免 Python/C 模运算行为差异导致的 NTT 逆变换失败。核心运算 (NTT、多项式乘法、CBD 采样) 均基于 hashlibsecrets 标准库。

服务端同时支持三种 kex 模式:hybrid / x25519 / dh2048,客户端和服务端在握手时协商选择,旧客户端无缝兼容。

多平台客户端

三种部署形态,同一套协议栈,完全互通。网络阻塞操作均在后台线程,UI 永不卡顿。

🖥

Windows GUI 客户端

基于 tkinter 的图形界面,天依青主题配色,圆角卡片设计。支持服务器选择、协议策略自选 (auto/wss/ws/https/http)、自定义背景图片 (自动缩放裁剪 + alpha 混合)、emoji 面板与颜文字、文件收发 (分块上传 + SHA-256 校验)、断线自动重连 (最多 5 次指数退避 1s/2s/4s/8s/16s)、动态运行日志栏 (可收起/展开/按级别着色)。字体渲染使用 Microsoft YaHei UI + Segoe UI Emoji 回退,DPI 感知,4K 屏不糊。

tkinterPillowPyInstaller单文件 exe

Windows CLI 客户端

纯命令行客户端,轻量高效,适合服务器环境、自动化脚本和快速测试。支持全功能操作:聊天历史记录 (本地持久化 JSON,最多 10000 条,支持关键字搜索)、联系人管理 (添加/删除/别名)、文件传输 (64KB 分块,SHA-256 校验)、群组聊天 (创建/加入/退出/群消息)、E2EE 加密消息、账号注销。可打包为单文件 exe,内嵌 Python 运行时,目标机器无需安装 Python。

Python 标准库PyInstaller单文件部署零依赖
🐧

Linux 服务端

Debian / Ubuntu 一键部署,四个 Python 文件即可运行。支持 systemd 服务管理 (开机自启、日志轮转、优雅重启)。纯标准库 + libsodium,apt 直接安装,无需 pip/conda。单进程异步架构 (asyncio),支持数千并发连接。内存占用 < 50MB,CPU 空闲时 < 1%。首次运行自动生成密钥材料,无需手动配置。

asynciosystemdapt install4 files

四层协议自动退让策略

wss:// (TLS)
失败 →
ws:// (明文)
失败 →
https:// 轮询
失败 →
http:// 保底

客户端自动尝试四层协议 (推荐 auto 模式),用户无需手动切换。WS 意外断开后自动重连,最多 5 次指数退避。 HTTPS 轮询模式 2 秒拉取一次,Token 30 分钟无活动自动过期续期。降级是单向的——一旦走 HTTPS 不会自动回切 WS,避免连接抖动。

服务器地址格式

输入自动转换说明
chat.example.comwss://chat.example.com/ws纯域名默认 wss:// (Cloudflare 友好)
127.0.0.1:8000ws://127.0.0.1:8000/wshost:port 形式,明文 ws
wss://chat.example.comwss://chat.example.com/ws显式 wss,走 TLS
ws://192.168.1.5:9000ws://192.168.1.5:9000/ws显式 ws 自定义端口
wss://域名/自定义路径原样使用自定义 WebSocket 路径

部署架构:Cloudflare Tunnel 免映射

服务端基于纯标准库 HTTP/WebSocket (RFC 6455),与 Cloudflare Tunnel 深度集成。客户端直连 wss:// 域名,无需本地端口映射,无需在客户端安装 cloudflared。

客户端
wss://域名
Cloudflare Edge
cloudflared tunnel
http://127.0.0.1:8000
E-Chat Server

为什么能免映射?

Cloudflare 的 HTTP 模式原生支持 WebSocket 升级 (RFC 6455)。客户端直连 wss://域名 时,Cloudflare 边缘节点直接把 WebSocket 升级请求通过 cloudflared 隧道转发到内网的 http://127.0.0.1:8000。全程 HTTP 协议族,不需要客户端侧再开 cloudflared 通道做 TCP 映射。

服务端入口 serve_client() 预读 HTTP 请求头,按 Upgrade 头分发:有 Upgrade: websocket 走 WebSocket 路径 (_serve_ws),否则走 HTTP API 路径 (_serve_http)。同一端口 (8000)、同一路由,两种协议共存,无需额外部署。

服务端部署 (Debian)

# 1. 安装依赖 sudo apt-get install -y python3 libsodium23 # 2. 上传四个文件到 /opt/echat # sec_toolkit.py native_crypto.py # ws_layer.py chat_server.py # 3. 启动 (首次运行自动生成密钥) python3 chat_server.py --host 0.0.0.0 --port 8000 # 4. systemd 服务 (开机自启) sudo systemctl enable --now echat

Cloudflare Tunnel 配置

# ~/.cloudflared/config.yml tunnel: <隧道ID> credentials-file: /root/.cloudflared/<ID>.json ingress: - hostname: chat.example.com service: http://127.0.0.1:8000 - service: http_status:404 # DNS: CNAME → <隧道ID>.cfargotunnel.com # 客户端填纯域名: chat.example.com # 自动转为: wss://chat.example.com/ws

HTTPS 降级通道

WebSocket 被网络中间设备拦截时 (企业代理/移动运营商/防火墙),自动切换到 HTTPS 轮询模式。POST /api/hello 完成握手 + 颁发 token,POST /api/sec 加密通信。加密强度与 WS 一致,用户体验无感知。

健康检查 & 管理 API

GET /api/health 明文端点供负载均衡器/监控系统探活,返回 status/uptime/users/online。管理员通过 CHAT_ADMIN_TOKEN 环境变量启用管理功能:stats/kick/lock/unlock/broadcast/list_users/delete_user 等。

跨通道在线用户合并

/who 返回的是 WS 在线 + HTTP 在线合并去重后的列表。两种通道的用户互相可见。HTTP 用户发给 WS 用户走实时推送,WS 用户发给 HTTP 用户走离线缓存 + poll 拉取。

性能调优建议

场景优化措施预期效果
高并发连接 (>1000)增加 ulimit -n 65536;Linux 内核调优 net.core.somaxconn=4096, tcp_tw_reuse=1支持万级并发
大文件传输增加分块大小至 256KB;启用 TCP_NODELAY 减少 Nagle 延迟吞吐量提升 3-5x
Cloudflare 缓存对静态资源 (bg.jpg) 设置 Cache-Control: public, max-age=31536000, immutable重复访问零加载
内存优化定期清理过期 HTTP token;限制离线消息上限 (默认 200 条/用户)长期运行稳定 < 100MB
日志轮转logrotate 配置:daily, rotate 30, compress, delaycompress磁盘占用可控

常见故障排查

cloudflared 连接失败:检查 tunnel 状态 (cloudflared tunnel list),确认 DNS CNAME 记录指向 <ID>.cfargotunnel.com,确认 ingress 规则中 hostname 与 DNS 一致。
WebSocket 400 错误:检查 Cloudflare Dashboard → Network → WebSocket 是否开启 (默认关闭)。
客户端连不上:检查服务端是否监听 0.0.0.0 (而非 127.0.0.1),检查防火墙是否放行 8000 端口 (仅需对 cloudflared 放行,无需公网开放)。
libsodium 找不到:Linux: apt install libsodium23;Windows: 将 libsodium.dll 放入客户端同目录或 PATH。

安全加固清单

1. server.key 权限设为 600,属主为 echat 专用用户
2. 禁用 root 运行服务端,使用专用系统用户
3. 配置 ufw 防火墙,仅开放 22 和 cloudflared 所需端口
4. 启用 systemd 的 ProtectSystem=strict, NoNewPrivileges=yes
5. CHAT_ADMIN_TOKEN 使用 32 字节随机值,通过环境变量注入
6. 定期运行 selftest.py 验证所有密码学原语正确性
7. 监控 /api/health 端点,设置告警 (连续 3 次失败通知)
8. 日志文件 server.log.enc 定期备份,离线存储

完整功能与技术矩阵

E-Chat v3.3 从 1.0 到 3.3 历经三次大版本迭代,代码总量超 7000 行,覆盖安全通信全场景。

功能模块详细说明实现文件
密钥协商X25519 / ML-KEM-768 混合 / DH-2048 兼容,三种模式握手协商sec_toolkit.py
端到端加密Signal Protocol 完整实现 (X3DH + Double Ratchet)signal_protocol.py + e2ee_client.py
原生密码学 FFIX25519 / Ed25519 / ChaCha20-Poly1305 / HMAC-SHA256,libsodium 绑定native_crypto.py
传输层WebSocket RFC 6455 完整实现 + HTTPS 降级 + TLS 指纹伪装ws_layer.py
口令认证PBKDF2-HMAC-SHA256 (200K 迭代) + 挑战-响应零知识证明sec_toolkit.py
防暴力破解连续 10 次失败锁定 2 分钟,WS/HTTP 双通道共享计数chat_server.py
文件传输64KB 分块上传 + SHA-256 完整性校验 + 10MB 上限 + 20 并发会话chat_server.py + chat_client.py
离线消息加密缓存到 offline.enc,每用户上限 200 条,上线自动推送chat_server.py
群组聊天创建/加入/退出/群消息广播,持久化到 groups.jsonchat_server.py
流量填充1024 字节对齐 + 随机化心跳 (20-45s) + 随机化心跳包大小ws_layer.py
TLS 指纹伪装JA3/JA4 对抗,模拟 Chrome 密码套件顺序,规避 DPI 识别ws_layer.py
ECH / 域前置Encrypted Client Hello 架构支持 + Domain Fronting 接口ws_layer.py
自动重连WS 断开后最多 5 次指数退避重连 (1s/2s/4s/8s/16s)gui_client.py
协议自动退让wss -> ws -> https -> http 四层自动切换,用户无感chat_client.py
加密日志seal(主密钥, 条目) 写入 server.log.enc,主密钥 chmod 600sec_toolkit.py
日志留存合规依法保留 185 天,超期自动清理过期条目 (原子重写)consent_manager.py
账号注销物理删除用户数据 (users.json/离线消息/文件会话),日志依法保留chat_server.py
管理员 APIstats/kick/lock/unlock/broadcast/list_users/list_online/list_locked/clear_offline/clear_files/delete_user/retentionchat_server.py
健康检查GET /api/health 明文端点,供监控系统探活chat_server.py
聊天历史本地持久化 JSON (~/.echat_history.json),最多 10000 条,支持搜索chat_client.py
联系人管理添加/删除/别名,持久化到 contacts.jsonchat_client.py
IP 归属地登录时通过 ip-api.com 查询国家/省份/城市/运营商并显示chat_server.py
隐私合规三重同意机制 (隐私政策/跨境传输/注销协议) + 版本校验consent_manager.py
本地数据加密PBKDF2 + HMAC-SHA256 加密 JSON,保护本地存储的敏感数据sec_toolkit.py
自检脚本覆盖全部加密原语 + E2EE 流程 + 文件传输 + 登录锁定 + HTTPS 降级selftest.py
配置管理JSON 配置文件 + 自动创建默认值 + 类型校验utils.py
代码规模一览:
chat_server.py 逾 2,200 行 (服务端核心,HTTP/WS 双协议 + 管理 API + 统计 + 健康检查)
chat_client.py 逾 1,600 行 (CLI 客户端,E2EE + 文件传输 + 历史记录 + 联系人 + HTTPS 降级)
gui_client.py 逾 2,000 行 (GUI 客户端,tkinter 主题 + 动态日志栏 + 自动重连)
sec_toolkit.py 逾 1,400 行 (安全工具集,X25519/ML-KEM-768/HKDF/加密日志/本地加密)
ws_layer.py 逾 800 行 (WebSocket RFC 6455 实现 + TLS 伪装 + 域前置)
signal_protocol.py + e2ee_client.py 逾 600 行 (Signal Protocol 完整实现)
native_crypto.py 逾 500 行 (libsodium FFI 绑定 + Python 回退)
consent_manager.py 逾 300 行 (隐私合规 + 同意机制 + 留存策略)
utils.py 逾 300 行 (配置管理 + 文件工具 + 校验)

关于 E-Chat Project

E-Chat 是一个密码学教学与研究用途的开源项目,旨在演示端到端加密通信的基本原理与实现方法。

版本演进

v1.0 — 初始版本

原始 TCP 安全通信

DH-2048 密钥协商 + HMAC 流式加密 + 挑战-响应登录。服务端加密日志、客户端命令行界面。

v1.1 — 传输层升级

WebSocket + Cloudflare Tunnel

从原始 TCP 改为 HTTP/WebSocket (RFC 6455),默认端口 8443 -> 8000。新增 HTTPS 降级通道和离线消息缓存。

v2.0 — 功能扩展

GUI + 文件传输 + 管理 API

新增 GUI 客户端 (tkinter)、文件传输 (分块 + SHA-256 校验)、登录防暴力破解、聊天历史记录、联系人管理、管理 API。代码量从 3,665 行扩展到 7,254 行。

v3.1 — 第一次飞升 (协议层)

后量子 + E2EE + 流量对抗

密钥协商升级为 X25519 + ML-KEM-768 混合 PQC。新增 Signal Protocol E2EE、流量填充、随机化心跳、TLS 指纹伪装、ECH/域前置、断线自动重连、emoji 面板、自定义背景。

v3.2 — 第二次飞升 (工程层)

libsodium 原生密码学

核心密码学运算下沉到 libsodium 原生库 FFI。协议层统一采用 ChaCha20-Poly1305 AEAD。新增 consent_manager.py 隐私合规模块。selftest.py 覆盖 E2EE 全流程。

v3.3 — 当前版本 (审查中)

HTTP 80 保底 + 动态日志栏 + IP 归属地

新增 HTTP 80 端口保底通道 (四层自动退让)。GUI 新增动态运行日志栏 (可收起/展开/按级别着色)。登录后显示 IP 归属地。去除界面主题字样,统一产品定位为"安全通信"。

当前状态:E-Chat v3.3 正在完成最后的代码审查与安全审计工作。审查内容涵盖:所有密码学原语的正确性验证 (selftest.py 全绿)、端到端流程的完整自检、libsodium FFI 边界的安全性检查、ML-KEM-768 纯 Python 实现的数学一致性验证、以及 Windows/Linux 双平台部署兼容性测试。审查通过后将正式发布。在此期间,欢迎通过下方联系方式与开发者交流。

权威技术参考

密码学标准

  • RFC 7748 — Elliptic Curves for Security (X25519)
  • RFC 8032 — Edwards-Curve Digital Signature Algorithm (Ed25519)
  • RFC 8439 — ChaCha20 and Poly1305 for IETF Protocols
  • RFC 5869 — HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
  • RFC 2104 — HMAC: Keyed-Hashing for Message Authentication
  • RFC 2898 — PKCS #5: Password-Based Cryptography (PBKDF2)
  • RFC 3526 — MODP Diffie-Hellman groups for IKE
  • RFC 6455 — The WebSocket Protocol

后量子密码 & 协议

部署与基础设施

E-Chat Project

Powered by RTX3100

📧

电子邮箱

rtx3100@163.com
🌐

官方域名

s1.2008828.xyz
🎬

B站空间

RTX3100
💬

技术交流

欢迎通过邮箱联系