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
308 lines
10 KiB
Markdown
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.
|