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.
297 lines
11 KiB
Markdown
297 lines
11 KiB
Markdown
# 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.
|