v3.0.0: Standalone release of ChaosCryptChat
Separate the encrypted messaging application into its own repository, with documentation written specifically for it. The application code is byte-for-byte identical to the version previously shipped inside the ChaosCrypt repository. No functional changes. Contents - qtmain.py: PyQt5 client together with the complete backend (cipher core, account and history databases, peer-to-peer networking, relay client, GUI) - server.py: optional central relay server, using only the standard library so it can be deployed on a bare machine Documentation - README: architecture, component map, wire protocol, requirements, installation, running, data locations, security properties, troubleshooting - SECURITY: threat model, protected properties, cryptographic building blocks, and known limitations including metadata exposure, plaintext local storage, P2P host trust, best-effort withdrawal, and the absence of a ratchet - LICENSE: MIT - CHANGELOG: release history - .gitignore: excludes application data, session tokens, local databases and media from version control Security notice Unaudited. Intended for learning, experimentation and personal use; not for production deployment or for confidentiality obligations that carry a regulatory, contractual or safety dimension.
This commit is contained in:
@@ -0,0 +1,273 @@
|
||||
# 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
|
||||
└── 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.
|
||||
|
||||
`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`.
|
||||
|
||||
---
|
||||
|
||||
## 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: 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
|
||||
└── server.py relay server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user