lockbitchat
3212138a0d
No protocol or message-protection changes. The version in the application header was a literal and had fallen behind, showing v5.6.0 while running 5.7.1. It now comes from package.json, and a test fails if a hard-coded one reappears or if meta.json, the README badge, the changelog and the docs disagree about the release. Documentation reorganised so that everything technical lives in doc/ with an index, and the root keeps only what belongs there by convention: README, SECURITY, CHANGELOG and LICENSE. - SECURITY.md rewritten. It listed a supported release line three major versions out of date and made claims the software does not make. It now states what is guaranteed, what is not, and how to report a problem. - SECURITY_DISCLAIMER.md and RESPONSIBLE_USE.md merged into doc/USE-POLICY.md, which says what the software cannot protect against rather than listing generic advice. - doc/SECURITY-ARCHITECTURE.md renamed to doc/ARCHITECTURE.md and rewritten around the session lifecycle, what verification gates, and how recovery works. - doc/CRYPTOGRAPHY.md rewritten: key schedule, the Double Ratchet, framing, and memory handling, with values taken from the source rather than restated. - doc/CONFIGURATION.md rewritten with the real file-type policy, ICE and TURN guidance, and the deployment caching rules that matter. - docs/webrtc-config.md moved to doc/CALLS.md and rewritten; the obsolete docs/webrtc-audit.md, a working document full of stale line numbers, removed along with the docs/ directory. - doc/CONTRIBUTING.md records what the recent regressions taught us about writing tests that can actually fail. - doc/README.md added as an index. Internal security review notes are excluded from the repository via .gitignore. Those describe attack paths against specific releases in enough detail to reproduce them, which is useful privately and harmful in public while users are still updating.
109 lines
4.7 KiB
Markdown
109 lines
4.7 KiB
Markdown
# Security Policy
|
|
|
|
## Reporting a vulnerability
|
|
|
|
Report privately, before public disclosure.
|
|
|
|
- Email: `SecureBitChat@proton.me`
|
|
- Include the affected version, steps to reproduce, the impact you see, and any
|
|
proof-of-concept material
|
|
- Please allow time for a fix to reach users before publishing details
|
|
|
|
There is no server to patch centrally. Every user has to load a new build, so
|
|
early publication exposes exactly the people who have not updated yet. That is
|
|
the only reason for the delay, and it is not indefinite: if you do not get a
|
|
response within a reasonable time, say so and set your own timeline.
|
|
|
|
Reports about a specific deployment (someone else's hosted instance, a TURN
|
|
server) should go to whoever operates it.
|
|
|
|
## Supported versions
|
|
|
|
| Release | Status |
|
|
| --- | --- |
|
|
| 5.7.x | Supported |
|
|
| 5.6.x | Superseded, update recommended |
|
|
| 5.5.x and earlier | Unsupported |
|
|
|
|
Because the application is served fresh from the network on each load, most users
|
|
are on the current release automatically. Installed progressive web app instances
|
|
update on the next launch after a new build is deployed.
|
|
|
|
Forward secrecy applies only when both peers are on 5.7.0 or later. The feature
|
|
is negotiated, and a session with an older peer falls back to the previous scheme.
|
|
The security panel in the application shows which is in force for the current
|
|
connection.
|
|
|
|
## What the software guarantees
|
|
|
|
Message content between two peers who have compared their safety code, against an
|
|
attacker on the network between them.
|
|
|
|
That guarantee has a precondition, and it is not optional. Completing the key
|
|
exchange proves that someone completed it, not who. The safety code comparison is
|
|
what identifies the peer, and it has to happen over a channel an attacker cannot
|
|
impersonate.
|
|
|
|
## What it does not guarantee
|
|
|
|
- A compromised endpoint. Malware, a hostile extension or physical access to an
|
|
unlocked device sees the plaintext.
|
|
- Behaviour of the person you are talking to. View-once and disappearing messages
|
|
are cooperative, not enforced against a determined recipient.
|
|
- Network privacy by default. A direct connection reveals your IP address to the
|
|
peer. Relay-only mode with your own TURN server prevents that, at the cost of
|
|
the relay operator seeing both addresses and traffic timing.
|
|
- The fact that you are using the software. That is visible to anyone watching
|
|
your network.
|
|
|
|
[doc/USE-POLICY.md](doc/USE-POLICY.md) goes into more detail.
|
|
|
|
## Current behaviour
|
|
|
|
**Verification.** The safety code is derived deterministically from shared
|
|
session material and both DTLS fingerprints, and is compared manually out of
|
|
band. A session becomes verified only after both peers confirm. Three incorrect
|
|
entries end it. Until verification completes, the session refuses control
|
|
messages from the peer: reconnection signalling, call setup, message deletion and
|
|
delivery receipts.
|
|
|
|
**Message protection.** Chat content is encrypted with a per-message key from the
|
|
Double Ratchet when both peers support it, and with per-session keys otherwise.
|
|
Ratchet message keys are destroyed after a single use, and each change of
|
|
direction re-keys the session root. Content reaches the interface through one
|
|
authenticated path; unauthenticated frames are dropped rather than displayed.
|
|
Decrypted text is sanitized before rendering.
|
|
|
|
**File transfer.** Metadata is validated before the user is prompted, every
|
|
transfer requires explicit consent, and no receive buffer is allocated before
|
|
consent. Accepted types are an explicit allowlist checked by extension, with MIME
|
|
type as a secondary signal. Executable and scriptable formats are blocked. Voice
|
|
notes are the one exception to the prompt, and qualify only if the receiver
|
|
confirms they are genuine audio within size and per-session budgets.
|
|
|
|
**Local storage.** Sensitive IndexedDB metadata is stored encrypted. Legacy
|
|
plaintext records migrate on read. Corrupted encrypted metadata fails closed. No
|
|
message history is written to disk.
|
|
|
|
**Cleanup.** Disconnecting closes the channels, clears verification state, and
|
|
overwrites the key material that can be overwritten. Timers, retries, cover
|
|
traffic, pending transfers and interface callbacks are all torn down.
|
|
|
|
## Verifying a build
|
|
|
|
```bash
|
|
npm audit
|
|
npm test
|
|
npm run build
|
|
```
|
|
|
|
The bundles in `dist/` are committed and served directly. They are not currently
|
|
verified against the sources by automation, so if you are reviewing this project
|
|
seriously, build from source and compare rather than reading `src/` alone.
|
|
|
|
## Limitations of this policy
|
|
|
|
This is a small project. There has been no independent cryptographic audit. The
|
|
documentation in [`doc/`](doc/) describes the design in enough detail to review
|
|
it, and that is the intended substitute until an audit happens.
|