Files
dvs a2d492e9f8 Add dvs_enc.py and document the two-module requirement
The client imports its backend from a module named `dvs_enc`, but the
repository only shipped that backend as `qtmain.py`. Starting the application
from a fresh clone therefore failed immediately:

    ModuleNotFoundError: No module named 'dvs_enc'

`dvs_enc.py` is now included. It carries the same content as `qtmain.py`, so
the import resolves to the identical implementation.

Verified end to end:

  - without dvs_enc.py: import qtmain raises ModuleNotFoundError
  - with dvs_enc.py:    import qtmain succeeds, all 14 backend classes present

Functional tests against a clean copy of the repository pass: text
round-trip, 4096-byte binary round-trip, HMAC authentication, AccountDB and
HistoryDB construction.

Also exercised the full client/server protocol against a live relay: register,
login, create group, join group, and ciphertext relay between two clients.
The relay forwards the payload verbatim without inspecting it.

Documentation
- README: new "Module layout" section explaining why both files are required,
  and what the failure looks like when dvs_enc.py is absent; repository layout
  and troubleshooting table updated to match
- CHANGELOG: structure table updated
2026-09-27 17:16:56 +08:00

308 lines
10 KiB
Markdown

# ChaosCryptChat
**End-to-end encrypted messaging built on the ChaosCrypt cipher.**
A desktop chat application with a PyQt5 client and an optional relay server.
Messages are encrypted on the client; the server only relays ciphertext and
never holds group keys.
| | |
|---|---|
| **Version** | 3.0.0 |
| **Default branch** | `chat` |
| **Licence** | MIT |
| **Python** | 3.8+ |
---
## Scope
ChaosCryptChat is an experiment in building a complete encrypted messaging
application on top of a non-standard cipher. It is intended for **learning,
experimentation and personal use**.
It has **not** been independently audited. It is not a replacement for
Signal, Matrix or any audited secure messenger, and it should not be relied on
where confidentiality carries regulatory, contractual or safety obligations.
The underlying cipher is documented separately in the
[ChaosCrypt](https://git.dvscloud.net/dvs/ChaosCrypt) repository, including
its full design and threat analysis. That analysis applies here too: the
construction is substantially stronger than its lack of audit suggests, but
the scope is deliberately narrow.
---
## What it does
- **End-to-end encryption.** The group key exists only on clients. The server
relays ciphertext and cannot decrypt anything.
- **Two group modes.**
- **End-to-end (P2P)** — peers connect directly; no server involved.
- **Central server** — a relay handles NAT traversal when direct
connections are not possible.
- **Text, images, files and voice messages.** All payload types are encrypted
the same way; binary data is handled losslessly.
- **Group management.** Create, join, rename, set announcements, kick members,
approve join requests.
- **Per-user key authentication.** Each member is issued a key used to sign
their messages, so one member cannot impersonate another.
- **Message integrity.** Each message carries an HMAC; a modified ciphertext
fails verification and is rejected.
- **Message withdrawal.** Sent messages can be recalled within a time window.
- **Local history.** Chat history is stored per account in SQLite and survives
restarts.
---
## Architecture
```
ChaosCryptChat/
├── qtmain.py PyQt5 client + the entire backend
├── dvs_enc.py the backend, under the name the client imports it by
└── server.py optional central relay server (standard library only)
```
`qtmain.py` is a single-file application: it contains the cryptographic core,
the account and history databases, the peer-to-peer networking layer, the
relay client, and the graphical interface. Running it directly starts the
client.
`dvs_enc.py` holds the same backend content under the module name the client
imports at runtime. **Both files must be present.** See
[Module layout](#module-layout) below.
`server.py` is deliberately independent and uses **only the Python standard
library**, so it can be deployed on a bare server without installing anything.
### Components in `qtmain.py`
| Component | Responsibility |
|---|---|
| `ChaosCryptCore` | The cipher: key generation, substitution, XOR layers |
| `SecureSession` | Per-session key handling, encryption and HMAC |
| `AccountDB` | Local accounts: salted password hashes |
| `HistoryDB` | Local message history per account and group |
| `ServerDB` | Local cache of relay state and issued user keys |
| `VoiceManager` | Audio recording and playback |
| `Message` | Message record and serialisation |
| `ChatServer` | Peer-to-peer listener (for P2P groups) |
| `ChatClient` | Peer-to-peer sender |
| `ServerConnection` | Client side of the central-relay protocol |
| `MessageItem` / `MessageList` | Message bubbles and the scrollable list |
| `LoginDialog` / `MainWindow` | Login and main window |
### Components in `server.py`
| Component | Responsibility |
|---|---|
| `ServerDB` | Users, groups, membership and announcements |
| `CentralServer` | Accept loop, authentication, group management, relay |
### Wire protocol
Messages are length-prefixed JSON frames:
```
uint32 big-endian length || UTF-8 JSON payload
```
Both ends implement the same framing, so the protocol is symmetric. The
handshake and command set are visible in the `_dispatch` methods of
`ChatClient`, `ServerConnection` and `CentralServer`.
---
## Module layout
The client expects its backend under the module name `dvs_enc`, and the
distribution ships that backend as `qtmain.py`. Both files must sit in the
same directory:
```
qtmain.py the application; run this
dvs_enc.py the backend module that qtmain.py imports
server.py the relay server; run this separately if you need it
```
`qtmain.py` defines the backend classes itself and then imports the same names
from `dvs_enc`. Because `dvs_enc.py` carries the identical content, the import
resolves to the same implementation and the application behaves consistently
whether it is launched as `python qtmain.py` or imported.
If `dvs_enc.py` is missing, starting the client fails immediately with:
```
ModuleNotFoundError: No module named 'dvs_enc'
```
So when copying the project, copy all three files — not just `qtmain.py`.
---
## Requirements
### Client (`qtmain.py`)
| Package | Purpose |
|---|---|
| `PyQt5` | Graphical interface |
| `Pillow` | Image handling |
| `numpy` | Fast buffer operations for audio and media |
| `pygame` | Audio playback |
| `sounddevice` | Audio recording |
| `pyaudio` | Alternative audio backend |
| `qrcode` | Group-key QR sharing |
Optional, depending on which features you use — the application degrades
gracefully when they are absent.
### Server (`server.py`)
None. The server uses only the standard library.
---
## Installation
```bash
git clone https://git.dvscloud.net/dvs/ChaosCryptChat.git
cd ChaosCryptChat
pip install PyQt5 Pillow numpy pygame sounddevice pyAudio qrcode
```
On Linux you may also need the system audio and Qt libraries:
```bash
sudo apt install python3-pyqt5 portaudio19-dev libsndfile1
```
---
## Running
### Start a P2P chat
```bash
python qtmain.py
```
Create an account, then create a group in **end-to-end** mode. Share the group
key with the people you want to talk to — they need it to decrypt messages.
### Start the relay server
On a machine with a reachable address:
```bash
python server.py # listens on 0.0.0.0:8666
python server.py 9000 # or choose a port
```
Clients then create a group in **central server** mode and point it at that
address. The server relays ciphertext; it never receives the group key.
> **Share group keys over a channel you already trust.** Anyone holding the
> group key can read the group's messages. The application cannot verify how
> you transmitted it.
---
## Where data lives
| Path | Contents |
|---|---|
| `data/users.db` | Local accounts (salted password hashes) |
| `data/chat_history.db` | Message history per account and group |
| `data/session.dat` | Session token, so you stay logged in |
| `data/server_state.db` | Cached relay state and issued user keys |
| `server_data/server.db` | Server-side users, groups, membership |
| `~/Documents/ChaosChat/media/` | Received and sent media |
| `~/Downloads/ChaosChat/` | Downloaded files |
The media cache can be cleared from the application's interface; clearing it
deletes the stored media permanently.
> **These files are not encrypted at rest.** The databases and the media cache
> hold plaintext. Protect the machine, or store the directories on an
> encrypted volume.
---
## Security properties
What the design does provide:
- **The server cannot read messages.** Group keys never leave clients. An
attacker who fully controls the relay obtains membership metadata and
traffic patterns, but not message contents.
- **Account passwords are not stored in plaintext.** They are hashed with a
random per-account salt.
- **Message tampering is detected.** Every message carries an HMAC over its
contents; verification failures are rejected rather than displayed.
- **Impersonation between members is prevented.** Each member's messages are
signed with a key issued to that member.
What to be aware of:
- **No independent audit.** The cipher, the protocol and this application have
not been reviewed by a third party.
- **Metadata is exposed to the relay.** Who is in a group, who talks to whom,
and when — none of that is hidden.
- **Keys are shared out of band.** If the group key is intercepted during
sharing, the group is compromised.
- **In P2P mode, the host is also a participant.** If the host's machine is
compromised, that group is compromised.
- **Local data is not encrypted.** See the table above.
- **Withdrawal is best-effort.** A recall marks a message as withdrawn and
notifies the server; members who are offline may still see the original.
- **Media handling depends on third-party libraries.** Audio and image
processing rely on `pygame`, `sounddevice` and `Pillow`, whose own security
is outside this project's scope.
For the cipher's own analysis — key space, resistance to differential, linear
and algebraic cryptanalysis, and behaviour under quantum algorithms — see the
`SECURITY.md` in the [ChaosCrypt](https://git.dvscloud.net/dvs/ChaosCrypt)
repository.
---
## Troubleshooting
| Symptom | Likely cause |
|---|---|
| `ModuleNotFoundError: dvs_enc` | `dvs_enc.py` not copied alongside `qtmain.py` |
| `ModuleNotFoundError: PyQt5` | Client dependencies not installed |
| No audio devices listed | `sounddevice` or PortAudio missing |
| Peers cannot connect in P2P mode | Firewall blocking the port, or NAT; use the relay |
| Cannot join a group | The group key does not match, or the host has not approved you |
| Messages appear as failures | HMAC verification failed — wrong key or altered data |
| Relay unreachable | `server.py` not running, or the port is blocked |
---
## Repository layout
```
.
├── README.md this file
├── SECURITY.md security model and known limitations
├── LICENSE MIT
├── CHANGELOG.md release history
├── .gitignore
├── qtmain.py client and backend; run this for the client
├── dvs_enc.py backend module imported by the client
└── server.py relay server; run this separately
```
---
## Licence
[MIT](LICENSE). Provided as-is, without warranty of any kind.
The authors accept no liability for any loss, disclosure or damage arising
from use of this software.