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:
dvs
2026-09-27 17:11:06 +08:00
commit faf60fd2e5
7 changed files with 5307 additions and 0 deletions
+296
View File
@@ -0,0 +1,296 @@
# Security Policy
**ChaosCryptChat — threat model, guarantees and known limitations**
| | |
|---|---|
| **Version** | 3.0.0 |
| **Status** | Unaudited |
| **Licence** | MIT |
---
## 1. Scope
This document describes what ChaosCryptChat protects, what it does not, and
where its trust boundaries lie.
The application is an experiment in building complete encrypted messaging on
top of a non-standard cipher. It is intended for **learning, experimentation
and personal use**. It has not been audited, and it is not a substitute for an
audited secure messenger such as Signal or Matrix.
If your threat model includes a well-resourced adversary, or if
confidentiality carries regulatory or contractual weight, use an audited
messenger instead. That is not a disclaimer bolted on to be safe — it is the
correct engineering choice, and this document will not pretend otherwise.
The cipher itself is documented separately in the
[ChaosCrypt](https://git.dvscloud.net/dvs/ChaosCrypt) repository: key space,
resistance to differential, linear and algebraic cryptanalysis, and behaviour
under Shor's and Grover's algorithms. Everything established there applies to
this application. What follows concerns the *application* layer.
---
## 2. Threat model
### Trusted
- **Client machines.** Messages are encrypted and decrypted in client process
memory. A compromised client is a compromised conversation.
- **The channel used to share a group key.** The application cannot verify how
the key reached the other members.
### Untrusted
- **The network.** Transmission may be observed, altered or replayed.
- **The relay server.** Worst-case assumption: the operator is adversarial and
the machine is fully compromised.
### Partially trusted
- **The group host, in P2P mode.** The host runs both the server and the
client. If the host is compromised, that group is compromised.
- **Group members.** Any member holding the group key can read the group's
messages. Membership is a trust decision.
---
## 3. What is protected
### 3.1 Message confidentiality
Message contents are encrypted on the client with the group key. The relay
receives ciphertext and relays it onward without the ability to decrypt.
```
plaintext
│ encrypt with group key (ChaosCrypt)
▼
ciphertext ── HMAC ──► network ──► relay ──► network ──► members
│ verify HMAC
│ decrypt
▼
plaintext
```
The group key is generated on the client and stored locally. It is never
transmitted to the relay as part of normal operation.
**Consequence of relay compromise:** message contents remain confidential, but
the attacker learns group membership, message timing, message sizes, and who
communicates with whom. See §5.1.
### 3.2 Message integrity
Every message carries an HMAC computed over its contents. A message whose HMAC
does not verify is rejected rather than displayed. An attacker who can modify
traffic in transit cannot alter a message without detection, and cannot forge
a new one without the key.
### 3.3 Account credentials
Account passwords are never stored in plaintext. Each account has a random
salt, generated per account, and only the salted hash is persisted. This
means a stolen `users.db` does not directly yield passwords — though password
strength still determines how long an offline attack takes.
### 3.4 Member authentication
On joining a group, each member is issued a user key used to sign their
messages. Other members verify the signature, so one member cannot send
messages that appear to come from another within the same group.
### 3.5 Group key verification
Joining a group requires presenting a credential derived from the group key.
A party without the group key cannot join, so the group is closed to those who
do not already hold the secret.
---
## 4. Cryptographic building blocks
| Purpose | Mechanism |
|---|---|
| Message content | ChaosCrypt cipher with the group key |
| Per-message key | Message key derived from the group key and a per-message nonce |
| Integrity | HMAC-SHA256 over the ciphertext |
| Member signing | Per-user key issued on joining a group |
| Password storage | Salted hash, random per-account salt |
| Group key sharing | Out of band; optionally by QR code |
### 4.1 On the choice of cipher
ChaosCrypt is not a standardised construction. Its key space is very large and
it resists the classical cryptanalytic techniques that depend on algebraic or
number-theoretic structure — but it has not been reviewed by third parties, and
it has not accumulated the decades of scrutiny that AES or ChaCha20 have.
That is the honest trade-off. This application exists to explore the design,
not to claim parity with audited primitives.
### 4.2 Group key distribution
The security of a group depends entirely on the security of the channel used
to share its key. The application supports QR sharing for convenience, which
still requires that the code itself is shown over a trusted channel. If the
key is intercepted during sharing, the group should be considered compromised
and the key rotated.
---
## 5. Known limitations
### 5.1 Metadata is not protected
The relay necessarily observes:
- which accounts exist and when they authenticate;
- which groups exist and who belongs to them;
- when messages are sent, to which group, and their sizes;
- the network addresses involved.
None of this is hidden. Reliable metadata protection requires a design with
cover traffic, padding, and mixnet-style routing, none of which is present
here. If metadata is part of your threat model, this application does not
address it.
### 5.2 Local data is stored in plaintext
| Path | Contents |
|---|---|
| `data/users.db` | Accounts and salted password hashes |
| `data/chat_history.db` | Full message history |
| `data/session.dat` | Session token |
| `data/server_state.db` | Cached relay state and user keys |
| `server_data/server.db` | Server-side users, groups, membership |
| `~/Documents/ChaosChat/media/` | Received and sent media |
Message history and media are stored **without encryption**. Anyone with
access to the filesystem — including anyone who steals the machine or gains
access to a backup — can read them directly. Protect the machine, or keep
these directories on an encrypted volume.
Clearing the media cache from the application deletes the stored media
permanently; there is no undo.
### 5.3 P2P mode: the host is a participant
In end-to-end mode there is no separate server — the group host runs both.
This has two consequences:
1. The host can observe connection metadata for the whole group.
2. If the host's machine is compromised, that group's security is
compromised, because the host holds both the group key and the routing.
Use relay mode when you do not want one participant to hold that position.
### 5.4 Message withdrawal is best-effort
Recalling a message marks it as withdrawn locally and notifies the relay, which
broadcasts the withdrawal. Members who are offline when the withdrawal is
announced may still see the original message when they reconnect. A member who
has already saved the content keeps it.
Withdrawal is a convenience feature, not a confidentiality guarantee, and it
should never be relied on to retract sensitive data.
### 5.5 Third-party dependencies
Audio recording and playback, image handling and QR generation rely on
`pygame`, `sounddevice`, `pyaudio`, `Pillow` and `qrcode`. The security of
those libraries is outside this project's scope. They run in-process, so a
vulnerability in any of them affects the application.
The relay server, by contrast, uses only the Python standard library.
### 5.6 No forward secrecy
The design does not implement a ratchet. Compromise of a group key exposes
messages encrypted under that key, both past and future, until the key is
rotated. Rotating the group key after a suspected compromise limits the
exposure to messages sent under the new key.
### 5.7 No protection against a compromised endpoint
Nothing in this design helps if the client machine is compromised. Malware,
keyloggers, a hostile operating system, or physical access to an unlocked
session all defeat end-to-end encryption, as they do for every messaging
application.
### 5.8 Reachability
Direct peer connections require that peers can reach each other. Firewalls and
NAT frequently prevent this, which is the reason the relay exists. Relay mode
degrades the metadata situation (§5.1) because all traffic passes through one
point.
---
## 6. Operational guidance
**Do**
- Generate a strong, unique password for each account.
- Share group keys in person, or over a channel you already trust.
- Rotate the group key if you suspect it was exposed.
- Keep the local data directories on an encrypted volume.
- Use relay mode when you do not want a single participant to hold routing
visibility.
- Run the relay on a machine you control, and keep it patched.
**Do not**
- Send anything through a group whose key was shared over an untrusted
channel.
- Rely on message withdrawal to retract sensitive content.
- Assume message history is protected because messages were encrypted in
transit — locally, it is plaintext.
- Deploy this where an audit or a compliance certification is required.
- Treat metadata as private.
---
## 7. Reporting a vulnerability
If you believe you have found a security issue, please report it privately
before disclosing it publicly. Include:
- a description of the issue;
- steps to reproduce, ideally minimal;
- the version affected;
- any suggested remediation.
Reports are welcome. Note that this project is maintained on a best-effort
basis and carries no warranty or support commitment, as set out in the MIT
licence.
---
## 8. Summary
**Protected:** message contents from the relay and from network observers;
message integrity; account passwords at rest in the database; member identity
within a group.
**Not protected:** metadata; local history and media at rest; anything against
a compromised endpoint; past messages after a key compromise; retraction
guarantees.
**The honest position:** this is a working, thoughtfully constructed encrypted
messaging application built on an unaudited cipher. It demonstrates a complete
end-to-end design — client-side encryption, key-based membership, integrity
verification and a relay that cannot read anything. It is genuinely useful for
learning and for personal use. It is not a replacement for an audited
messenger, and it should not be treated as one.
---
## 9. Licence
MIT. Provided as-is, without warranty of any kind. See [LICENSE](LICENSE).
The authors accept no liability for any loss, disclosure or damage arising
from use of this software.