mirror of
https://github.com/Stone-Red-Code/EchoHub.git
synced 2026-09-04 00:56:05 +02:00
feat: Implement message encryption and decryption support
- Added IMessageEncryptionService and its implementation MessageEncryptionService for handling message encryption. - Updated ChannelsController and ChatService to encrypt messages before storing and sending. - Introduced encryption key retrieval endpoint in ServerController. - Modified EchoHubDbContext to accommodate increased message content and embed JSON lengths for encrypted data. - Created migrations to support encryption-related database changes. - Enhanced FirstRunSetup to ensure encryption key is generated if not present. - Updated appsettings.example.json to include encryption configuration. - Added comprehensive unit tests for encryption service and compatibility tests between client and server encryption.
This commit is contained in:
HueByte
@@ -0,0 +1,137 @@
|
||||
# Message Encryption
|
||||
|
||||
EchoHub uses application-layer AES-256-GCM encryption to protect message content in transit between clients and the server. This is an additional layer on top of TLS, protecting against ISPs, proxies, and any middleman that can inspect HTTPS traffic (e.g. corporate proxies with trusted root CA certificates).
|
||||
|
||||
## How It Works
|
||||
|
||||
```text
|
||||
TUI Client Server TUI Client
|
||||
│ │ │
|
||||
│ encrypt(plaintext) │ │
|
||||
│ ──── $ENC$v1$... ──────────────► │ │
|
||||
│ │ decrypt → validate/sanitize │
|
||||
│ │ fetch embeds on plaintext │
|
||||
│ │ encrypt(plaintext) │
|
||||
│ │ ──── $ENC$v1$... ──────────────► │
|
||||
│ │ │ decrypt → display
|
||||
│ │ │
|
||||
│ │ (optional) encrypt for DB │
|
||||
│ │ store to SQLite │
|
||||
```
|
||||
|
||||
1. **Client encrypts** the message before sending it over SignalR
|
||||
2. **Server decrypts** to validate content, sanitize newlines, and fetch link embeds
|
||||
3. **Server re-encrypts** with a fresh nonce and broadcasts to all connected SignalR clients
|
||||
4. **Clients decrypt** the broadcast and display the plaintext
|
||||
5. **IRC clients** receive plaintext automatically (the IRC broadcaster decrypts before forwarding)
|
||||
|
||||
Each encryption uses a random 12-byte nonce, so the same message produces different ciphertext every time.
|
||||
|
||||
## Encryption Key
|
||||
|
||||
A 256-bit AES key is auto-generated on first server startup and saved to `appsettings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Encryption": {
|
||||
"Key": "base64-encoded-32-byte-key",
|
||||
"EncryptDatabase": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The key is generated by `FirstRunSetup` using `RandomNumberGenerator.GetBytes(32)`. If the key is missing or empty when the server starts, a new one is created automatically.
|
||||
|
||||
Clients fetch the key after login via an authenticated endpoint (`GET /api/server/encryption-key`). No manual configuration is needed on the client side.
|
||||
|
||||
## Encrypted Content Format
|
||||
|
||||
Encrypted content uses a self-describing format:
|
||||
|
||||
```text
|
||||
$ENC$v1${nonce_base64}${ciphertext+tag_base64}
|
||||
```
|
||||
|
||||
- **`$ENC$v1$`** — version prefix (allows future algorithm changes)
|
||||
- **Nonce** — 12 bytes, Base64-encoded, randomly generated per message
|
||||
- **Ciphertext + Tag** — AES-256-GCM output with 16-byte authentication tag appended
|
||||
|
||||
The authentication tag ensures both confidentiality and integrity — any tampering with the ciphertext is detected during decryption.
|
||||
|
||||
## Database Encryption (Optional)
|
||||
|
||||
By default, messages are stored as **plaintext** in the database. Transport encryption still protects everything on the wire, but the SQLite file itself contains readable messages.
|
||||
|
||||
To encrypt messages at rest, enable the setting:
|
||||
|
||||
```json
|
||||
{
|
||||
"Encryption": {
|
||||
"Key": "...",
|
||||
"EncryptDatabase": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Behavior by Setting
|
||||
|
||||
| Setting | DB Storage | Transport | Key Rotation Risk |
|
||||
|---------|-----------|-----------|-------------------|
|
||||
| `false` (default) | Plaintext | Encrypted | None — stored data is unaffected |
|
||||
| `true` | Encrypted | Encrypted | Changing the key makes old messages unreadable |
|
||||
|
||||
### Mixed Content
|
||||
|
||||
The server handles mixed encrypted/plaintext content in the database gracefully. When reading messages:
|
||||
|
||||
- Content starting with `$ENC$v1$` is decrypted
|
||||
- Everything else is treated as plaintext
|
||||
|
||||
This means you can safely toggle `EncryptDatabase` at any time. Old messages remain readable regardless of the current setting.
|
||||
|
||||
### Enabling Encryption at Rest
|
||||
|
||||
When you set `EncryptDatabase: true`, only **new messages** are encrypted going forward. Existing plaintext messages in the database are not retroactively encrypted. This is intentional — it keeps key rotation safe and avoids irreversible bulk changes.
|
||||
|
||||
### Key Rotation
|
||||
|
||||
Changing the encryption key is safe:
|
||||
|
||||
- **Plaintext messages** — always readable regardless of key
|
||||
- **Messages encrypted with the old key** — will show `[encrypted message — decryption failed]`
|
||||
- **New messages** — encrypted with the new key going forward
|
||||
|
||||
If you need to recover old encrypted messages, restore the original key from a backup of `appsettings.json`. Since plaintext messages are never retroactively encrypted, you'll never lose access to your entire history from a key change.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### What This Protects Against
|
||||
|
||||
- **Passive network sniffing** — messages are encrypted even if captured off the wire
|
||||
- **ISP/proxy inspection** — content is encrypted at the application layer, independent of TLS
|
||||
- **Database theft** (when `EncryptDatabase: true`) — SQLite file contains only ciphertext
|
||||
|
||||
### Limitations
|
||||
|
||||
- **TLS-inspecting proxies** — if a corporate proxy terminates TLS with a trusted root CA, it can intercept the key exchange (`GET /api/server/encryption-key`) and read all traffic. A future upgrade to ECDH key exchange would address this.
|
||||
- **Server has full access** — the server decrypts all messages for processing. This is not end-to-end encryption between users; it's transport encryption between client and server.
|
||||
- **IRC clients receive plaintext** — IRC is an open protocol and third-party clients cannot participate in the encryption scheme.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Messages show `[encrypted message — decryption failed, try re-logging to fetch the latest key]`
|
||||
|
||||
The client's encryption key doesn't match the server's. This happens when:
|
||||
|
||||
- The server's encryption key was rotated while the client was connected
|
||||
- The client cached a stale key
|
||||
|
||||
**Fix**: Disconnect and reconnect (re-login). The client fetches the current key on each login.
|
||||
|
||||
### Messages show `[encrypted message — decryption failed]` in channel history
|
||||
|
||||
The server cannot decrypt messages stored in the database. This happens when:
|
||||
|
||||
- `EncryptDatabase` was enabled, and the key was changed afterwards
|
||||
|
||||
**Fix**: Restore the original key from a backup. There is no way to recover messages encrypted with a lost key.
|
||||
@@ -0,0 +1,32 @@
|
||||
# v0.2.4 - E2E Message Encryption
|
||||
|
||||
## Features
|
||||
|
||||
### E2E Message Encryption
|
||||
|
||||
- Application-layer AES-256-GCM encryption for all message content between client and server
|
||||
- Protects against ISPs, proxies, and any middleman reading chat messages — even if TLS is compromised
|
||||
- 256-bit encryption key auto-generated on first server startup and saved to `appsettings.json`
|
||||
- Client fetches the encryption key automatically after login via `GET /api/server/encryption-key`
|
||||
- Client encrypts messages before sending via SignalR; server decrypts for validation and processing
|
||||
- Server broadcasts encrypted content to SignalR clients; client decrypts transparently — no user action required
|
||||
- Optional database encryption at rest via `Encryption:EncryptDatabase` setting (disabled by default)
|
||||
- When enabled: new messages encrypted before DB storage (existing plaintext messages are not retroactively encrypted)
|
||||
- When disabled: messages stored as plaintext, no risk of data loss from key rotation
|
||||
- Reads handle mixed content (encrypted + plaintext) regardless of setting — safe to toggle at any time
|
||||
- Key rotation is safe: old plaintext stays readable, new messages use the new key
|
||||
- IRC gateway automatically decrypts messages before forwarding to IRC clients (plaintext over IRC)
|
||||
- Encrypted content format: `$ENC$v1${nonce}${ciphertext+tag}` (Base64, 12-byte nonce, 16-byte auth tag)
|
||||
- Server strips `$ENC$` prefix from user-typed messages to prevent format spoofing
|
||||
- Graceful fallback: if decryption fails, shows `[encrypted message — decryption failed, try re-logging to fetch the latest key]`
|
||||
|
||||
## Infrastructure
|
||||
|
||||
- `IMessageEncryptionService` interface in Core; `MessageEncryptionService` server implementation and `ClientEncryptionService` client implementation
|
||||
- `EncryptionKeyResponse` DTO and `GET /api/server/encryption-key` endpoint (authenticated, rate-limited)
|
||||
- `FirstRunSetup.EnsureEncryptionKey()` auto-generates AES-256 key on first server run
|
||||
- `Encryption:EncryptDatabase` server setting (default `false`) controls whether messages are encrypted at rest
|
||||
- DB column max lengths increased for encrypted content: `Message.Content` 2000 → 16000, `Message.EmbedJson` 8000 → 32000
|
||||
- EF Core migration: `AddEncryptionSupport`
|
||||
- Encryption test suite: server-side, client-side, and cross-compatibility tests (87 total)
|
||||
- Documentation article: `docs/articles/encryption.md`
|
||||
Reference in New Issue
Block a user