dvs faf60fd2e5 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.
2026-09-27 17:11:06 +08:00

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 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

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:

sudo apt install python3-pyqt5 portaudio19-dev libsndfile1

Running

Start a P2P chat

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:

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 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. 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.

S
Description
End-to-end encrypted messaging built on the ChaosCrypt cipher. PyQt5 client + relay server.
Readme MIT
97 KiB
2026-09-27 09:17:01 +00:00
Languages
Python 100%