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