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:
+296
@@ -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.
|
||||
Reference in New Issue
Block a user