296 lines
16 KiB
Markdown
296 lines
16 KiB
Markdown
<p align="center">
|
||
<img src="assets/logo.png" alt="Sanctum Logo" width="220"/>
|
||
</p>
|
||
|
||
# Sanctum 🛡️
|
||
|
||
**Verschlüsselter Ein-Datei-Container unter Windows & Linux im reinen Userland**
|
||
|
||
Sanctum ist eine eigenständige, speichersichere und hochperformante CLI-Anwendung in Rust, die verschlüsselte Ein-Datei-Container (`.sanctum`) unter Windows 10/11 und Linux im reinen Userland verwaltet.
|
||
|
||
- **100% Userland**: Keine Administratorrechte erforderlich, keine Kernel-Treiber (weder WinFsp noch Dokan).
|
||
- **Windows Explorer- & Desktop-Integration**: Einhängen als nativer Netzlaufwerk-Buchstabe (Z: abwärts) via lokalem WebDAV (`127.0.0.1`), Explorer-Kontextmenü und System-Tray-Icon unter Windows sowie `gio mount` / `.desktop`-MIME unter Linux.
|
||
- **Native Synchronisation (`sanctum sync`)**: RSync-artiger bidirektionaler Dateiabgleich (`Push` & `Pull`) mit 1-MB-Chunk-Streaming direkt in SQLite. Umgeht das fundamentale 4-GB-Dateilimit des Windows WebClient-Dienstes (`0x800700DF`) für Dateien beliebiger Größe (5 GB, 50 GB, 500 GB+). Inklusive `--dry-run` Simulation, `--delete` Spiegelung und `--checksum` Hashprüfung.
|
||
- **In-Place Self-Upgrade (`sanctum upgrade`)**: Aktualisiert das laufende Binary per Knopfdruck direkt über Gitea Releases. Löst Windows File-Locking via `self-replace` und verifiziert jedes Release kryptografisch gegen `SHA256SUMS.txt`.
|
||
- **Transparente LZ4-Kompression**: Automatische Kompression von Chunks mit On-the-Fly-Dekompression und adaptivem Fallback.
|
||
- **Anti-Forensik & Storage Compaction**: Inkrementelles Auto-Vacuum zur physikalischen Freigabe von Speicherplatz und kryptografisches Überschreiben (Shredding) von Datenblöcken mit CSPRNG-Rauschen vor dem Löschen.
|
||
- **Plausible Deniability (Hidden Safe)**: Dual-Slot-Header. Ein unbenutzter Slot enthält uniformes CSPRNG-Rauschen, das sich nicht von einem echten Hidden Vault unterscheiden lässt. Volle Dateinamen-Verschlüsselung im Hidden Vault.
|
||
- **OpSec & Explorer Anti-Leak Shield**: Blockiert Explorer-Spuren (`Thumbs.db`, `desktop.ini`, `*.tmp`, `:Zone.Identifier`), automatischer Unmount bei Inaktivität oder Windows-Sitzungssperre (`Win + L`).
|
||
- **Disaster Recovery**: 24-Wort BIP-39 Mnemonic Seed Phrases, konsistente Online-Backups via SQLite Online Backup API und kryptografische Vollprüfung (`sanctum verify`).
|
||
- **Statisches Single-Binary**: Standalone-Executables ohne externe DLL-Abhängigkeiten (`sanctum.exe` für Windows, statisches musl-ELF für Linux).
|
||
|
||
> 💡 **Neu bei Sanctum?** Eine kompakte Schritt-für-Schritt-Anleitung findest du in der [Schnellstartanleitung (QUICKSTART.md)](QUICKSTART.md). Hinweise zur Installation via Scoop oder Winget gibt es im [Installations-Guide (INSTALL.md)](INSTALL.md).
|
||
|
||
---
|
||
|
||
## 🔐 Kryptografie & Sicherheitsarchitektur
|
||
|
||
- **Schlüsselableitung (Argon2id)**:
|
||
Aus dem Master-Passwort wird mittels `Argon2id` ($M=64\,\text{MB}, T=3, P=4$) ein 256-Bit Key Encryption Key (KEK) abgeleitet.
|
||
- **Data Encryption Key (DEK)**:
|
||
Zufälliger 256-Bit Schlüssel via CSPRNG (`OsRng`). Der DEK wird mit dem KEK via AES-256-GCM verschlüsselt und im Header abgelegt.
|
||
- **Speichersicherheit (Zeroize)**:
|
||
Alle Schlüsselstrukturen implementieren das `Zeroize`-Trait (`Zeroizing<[u8; 32]>`), um sensible Schlüsseldaten beim Verlassen des Gültigkeitsbereichs im RAM sofort sicher zu nullen.
|
||
- **Chunk-Verschlüsselung (AES-256-GCM)**:
|
||
Dateien werden in Blöcken von 1 MB verschlüsselt.
|
||
- **Swap-Attack-Schutz**:
|
||
Als Authenticated Associated Data (AAD) werden `node_id` (8 Bytes LE) und `chunk_index` (8 Bytes LE) an jeden Block gebunden. Ein Vertauschen von Chunks zwischen Dateien oder innerhalb einer Datei führt zum Authentifizierungsfehler.
|
||
- **Plausible Deniability (Multi-Slot)**:
|
||
Konstante 2-Slot-Architektur. Slot 0 dient als Standard-/Decoy-Vault, Slot 1 als Hidden Vault oder CSPRNG-Dummy. Ein Angreifer kann mathematisch nicht feststellen, ob Slot 1 ungenutzt ist oder einen zweiten Tresor birgt.
|
||
- **Dateinamen-Verschlüsselung**:
|
||
Dateinamen im Hidden Vault werden mit frischen CSPRNG-Nonces und AES-256-GCM verschlüsselt in der Datenbank gespeichert.
|
||
- **Kryptografisches Chunk-Shredding**:
|
||
Vor jedem Löschen oder Kürzen werden Chunk-Payloads in der SQLite-Datenbank mit CSPRNG-Rauschen überschrieben.
|
||
|
||
---
|
||
|
||
## 📦 Speicher- & Kompressions-Engine
|
||
|
||
Der Container besteht aus exakt **einer** Host-Datei (`.sanctum`), die dynamisch bis über 100 GB wachsen kann:
|
||
|
||
- **SQLite3 WAL & Auto-Vacuum**:
|
||
- `PRAGMA auto_vacuum = INCREMENTAL;`
|
||
- `PRAGMA journal_mode = WAL;`
|
||
- `PRAGMA synchronous = NORMAL;`
|
||
- `PRAGMA page_size = 8192;`
|
||
- **LZ4-Kompression**:
|
||
Chunks werden vor der Verschlüsselung via `lz4_flex` komprimiert. Spart die Kompression weniger als 64 Bytes (z. B. bei bereits komprimierten Bildern oder Videos), wird adaptiv die Rohform verschlüsselt.
|
||
- **Speicherplatzrückgabe**:
|
||
Durch `PRAGMA auto_vacuum = INCREMENTAL;` können freigewordene SQLite-Pages beim Aushängen oder via `sanctum compact` vollständig an das Windows-Hostdateisystem zurückgegeben werden.
|
||
|
||
---
|
||
|
||
## 🚀 Kompilieren
|
||
|
||
Voraussetzungen: Rust (>= 1.85) mit GCC/MinGW-Toolchain für SQLite:
|
||
|
||
```powershell
|
||
cargo build --release
|
||
```
|
||
|
||
Das fertige Binary befindet sich unter `target/release/sanctum.exe`.
|
||
|
||
---
|
||
|
||
## 🛠️ CLI-Referenz & Verwendung
|
||
|
||
### 1. Container initialisieren
|
||
|
||
```powershell
|
||
# Standard-Container anlegen:
|
||
sanctum.exe init --path "C:\Pfad\tresor.sanctum"
|
||
|
||
# Container mit Plausible Deniability (Decoy + Hidden Safe) anlegen:
|
||
sanctum.exe init --path "C:\Pfad\tresor.sanctum" --with-hidden
|
||
```
|
||
*(Gibt nach Passworteingabe eine 24-Wort BIP-39 Notfall-Wiederherstellungskarte aus).*
|
||
|
||
---
|
||
|
||
### 2. Container einbinden (Mount)
|
||
|
||
```powershell
|
||
# Automatische Wahl des nächsten freien Laufwerksbuchstabens (z. B. Z:):
|
||
sanctum.exe mount --path "C:\Pfad\tresor.sanctum"
|
||
|
||
# Bestimmten Laufwerksbuchstaben erzwingen:
|
||
sanctum.exe mount --path "C:\Pfad\tresor.sanctum" --drive S
|
||
|
||
# Mit Inaktivitäts-Timeout (in Sekunden):
|
||
sanctum.exe mount --path "C:\Pfad\tresor.sanctum" --idle-timeout 300
|
||
|
||
# Lautloser Stealth-Modus (keine Banner/Token-Ausgabe, kein Explorer-Auto-Open):
|
||
sanctum.exe mount --path "C:\Pfad\tresor.sanctum" --stealth
|
||
|
||
# Explorer-Auto-Open gezielt unterdrücken (maximale ShellBag-OpSec):
|
||
sanctum.exe mount --path "C:\Pfad\tresor.sanctum" --no-open
|
||
```
|
||
- **Automatischer Slot-Unlock**: Sanctum prüft das eingegebene Passwort gegen alle Slots und bindet automatisch den entsprechenden Tresor ein (Slot 0 Decoy oder Slot 1 Hidden Vault).
|
||
- **Windows Explorer**: Das gemountete Laufwerk wird standardmäßig im Explorer geöffnet (abschaltbar via `--no-open` oder `--stealth`).
|
||
- **System-Tray**: Ein Schild-Icon im Windows Infobereich erlaubt Statusabfrage und direktes Aushängen.
|
||
- **Beenden**: `Ctrl+C` im Terminal oder Rechtsklick im Tray -> "Aushängen & Beenden" führt einen sauberen Unmount, Speicher-Compaction und WAL-Checkpoint durch.
|
||
|
||
---
|
||
|
||
### 3. Container manuell trennen
|
||
|
||
```powershell
|
||
sanctum.exe unmount --drive S
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Master-Passwort ändern
|
||
|
||
```powershell
|
||
sanctum.exe passwd --path "C:\Pfad\tresor.sanctum"
|
||
```
|
||
Ändert das Passwort über Key-Rewrapping in Sekundenbruchteilen, ohne die Nutzdaten neu verschlüsseln zu müssen.
|
||
|
||
---
|
||
|
||
### 5. Disaster Recovery & Notfallschlüssel
|
||
|
||
```powershell
|
||
# 24-Wort BIP-39 Notfallschlüssel anzeigen:
|
||
sanctum.exe recovery-key --path "C:\Pfad\tresor.sanctum"
|
||
|
||
# Konsistentes Online-Backup erstellen (auch während Mount möglich):
|
||
sanctum.exe backup --path "C:\Pfad\tresor.sanctum" --output "D:\Backup\tresor_backup.sanctum"
|
||
|
||
# Container aus Backup wiederherstellen:
|
||
sanctum.exe restore --path "D:\Backup\tresor_backup.sanctum" --output "C:\Pfad\tresor_restored.sanctum"
|
||
|
||
# Vollständige Integritätsprüfung (B-Tree, Knoten und AEAD-Tags aller Chunks):
|
||
sanctum.exe verify --path "C:\Pfad\tresor.sanctum"
|
||
```
|
||
|
||
---
|
||
|
||
### 6. Storage Compaction (Speicherbereinigung)
|
||
|
||
```powershell
|
||
# Freelist-Pages an Windows freigeben und Container verkleinern:
|
||
sanctum.exe compact --path "C:\Pfad\tresor.sanctum"
|
||
|
||
# Nur eine begrenzte Anzahl Pages freigeben:
|
||
sanctum.exe compact --path "C:\Pfad\tresor.sanctum" --pages 500
|
||
```
|
||
|
||
---
|
||
|
||
### 7. Windows Explorer Kontextmenü-Integration
|
||
|
||
```powershell
|
||
# .sanctum-Dateien für Rechtsklick ("In Sanctum öffnen") in HKCU registrieren (ohne Adminrechte):
|
||
sanctum.exe register
|
||
|
||
# Registrierung wieder rückstandslos entfernen:
|
||
sanctum.exe unregister
|
||
```
|
||
|
||
---
|
||
|
||
### 8. Native Synchronisation (`sanctum sync`)
|
||
|
||
Sanctum bietet eine native, rsync-ähnliche Synchronisations-Engine, die Dateien direkt auf Datenbank- und Chunk-Ebene überträgt. Dies löst das fundamentale Problem des Windows WebClient-Dienstes (`mrxdav.sys`), welcher beim Kopieren über gemountete WebDAV-Netzlaufwerke konstruktionsbedingt auf maximal 4 GB pro Datei beschränkt ist (`FileSizeLimitInBytes` / Fehler `0x800700DF`).
|
||
|
||
```powershell
|
||
# 1. Vorab-Simulation ausführen (Dry-Run / risikolos prüfen):
|
||
sanctum.exe sync --path "C:\Pfad\tresor.sanctum" "C:\Users\User\Downloads" /Downloads --dry-run
|
||
|
||
# 2. Ordner synchronisieren (unfertige Downloads und Temporärdateien ausschließen):
|
||
sanctum.exe sync --path "C:\Pfad\tresor.sanctum" "C:\Users\User\Downloads" /Downloads --exclude "*.crdownload" --exclude "*.tmp"
|
||
|
||
# 3. Exakte 1:1 Spiegelung (löscht verwaiste Dateien im Ziel):
|
||
sanctum.exe sync --path "C:\Pfad\tresor.sanctum" "C:\Users\User\Dokumente" /Dokumente --delete
|
||
|
||
# 4. Mit kryptografischer Inhaltsprüfung (SHA-256 Hashes vergleichen):
|
||
sanctum.exe sync --path "C:\Pfad\tresor.sanctum" "C:\Users\User\Projekte" /Projekte --checksum
|
||
|
||
# 5. Daten aus dem Tresor wiederherstellen (Pull / Container -> Host):
|
||
sanctum.exe sync --path "C:\Pfad\tresor.sanctum" /Downloads "D:\Wiederhergestellt\Downloads" --pull
|
||
```
|
||
|
||
- **Dateigrößen**: Dateien beliebiger Größe (**5 GB, 50 GB, 500 GB+**) werden in 1-MB-Streaming-Chunks mit AES-256-GCM direkt übertragen.
|
||
- **Fast-Delta Check**: Dateien mit identischer Größe und Modifikationszeitstempel (`mtime`) werden sofort übersprungen.
|
||
- **Metadaten-Erhaltung**: Datei-Zeitstempel (`mtime`) werden in beide Richtungen exakt konserviert.
|
||
|
||
---
|
||
|
||
### 9. In-Place Self-Upgrade (`sanctum upgrade`)
|
||
|
||
Aktualisiert die laufende Sanctum-Executable direkt über die offizielle Gitea-Releases-API auf die neueste Version, ohne manuelle Browser-Downloads oder separate Paketmanager:
|
||
|
||
```powershell
|
||
# Nur prüfen, ob ein Update verfügbar ist:
|
||
sanctum.exe upgrade --check
|
||
# oder mit dem Alias:
|
||
sanctum.exe update -c
|
||
|
||
# Interaktives Upgrade durchführen (zeigt Release-Details und fragt nach Bestätigung):
|
||
sanctum.exe upgrade
|
||
|
||
# Vollautomatisches Upgrade ohne Rückfragen (z. B. in Skripten):
|
||
sanctum.exe upgrade -y
|
||
|
||
# Upgrade erzwingen (Neuinstallation / Reinstall derselben Version):
|
||
sanctum.exe upgrade --force
|
||
```
|
||
|
||
- **Plattformunabhängig**: Löst das Windows-Dateilock (`ERROR_ACCESS_DENIED`) via `self-replace` und unterstützt ebenso Linux (statisches musl ELF).
|
||
- **Kryptografische Integrität**: Das heruntergeladene Binary wird vor dem Ersetzen zwingend gegen die offizielle `SHA256SUMS.txt` via SHA-256 verifiziert.
|
||
- **Paketmanager-Harmonie**: Erkennt automatisch Installationen via Scoop (`scoop update sanctum`) oder Winget (`winget upgrade HaraldPansi.Sanctum`) und warnt den Benutzer.
|
||
|
||
---
|
||
|
||
## 🛡️ OpSec & Explorer Anti-Leak Shield
|
||
|
||
Sanctum schützt vertrauliche Daten vor unbeabsichtigten Windows-Spuren:
|
||
|
||
1. **Anti-Leak Dateifilter**: Unterdrückt das Anlegen von `Thumbs.db`, `desktop.ini`, Office-Sperrdateien (`~$*`), temporären Dateien (`*.tmp`) und NTFS Alternate Data Streams (`:Zone.Identifier`).
|
||
2. **Inactivity Auto-Lock**: Erkennt Inaktivität anhand echter Lese-/Schreibzugriffe und trennt den Container automatisch nach Erreichen des Timeouts.
|
||
3. **Session Lock Detection**: Reagiert über `WTSRegisterSessionNotification` sofort auf Windows-Sitzungssperren (`Win + L`) oder Abmeldungen und schließt den Container blitzschnell ab.
|
||
4. **RAM-Paging-Schutz (`VirtualLock`)**: Verriegelt sensible Schlüsselstrukturen (`DEK`) im physischen RAM, um das Auslagern in `pagefile.sys` oder `swapfile.sys` durch den Windows Memory Manager zu verhindern.
|
||
5. **ShellBag & Forensik-OpSec**: Über die Optionen `--no-open` oder `--stealth` kann das automatische Öffnen des Windows Explorers vollständig unterdrückt werden, um zu verhindern, dass Ordnernamen persistent im ShellBag-Cache (`UsrClass.dat`) protokolliert werden.
|
||
6. **VFS Carrier-Schutz**: Die im Decoy-Tresor sichtbare Alibi-Trägerdatei wird im VFS gegen versehentliches Löschen, Überschreiben oder Umbenennen geschützt.
|
||
7. **Power-Loss Crash-Consistency**: Atomare Bündelung von Block-Schreiboperationen und Metadaten-Größenaktualisierungen in einer SQLite-Transaktion verhindert Datenkorruption bei plötzlichem Stromausfall.
|
||
|
||
---
|
||
|
||
## 🔧 Windows-Kompatibilität & AV/EDR-Tuning
|
||
|
||
### Windows Defender SmartScreen ("Unbekannter Herausgeber")
|
||
Wird die Binärdatei über einen Webbrowser heruntergeladen, versieht Windows sie mit dem *Mark-of-the-Web* (MotW). Da Open-Source-Projekte über kein kostenpflichtiges EV-Code-Signing-Zertifikat verfügen, zeigt Windows beim ersten Start den blauen SmartScreen-Dialog:
|
||
- **Einmalige Freigabe im Dialog:** Klick auf **"Weitere Informationen"** $\to$ **"Trotzdem ausführen"**.
|
||
- **Schnellfreigabe via PowerShell:**
|
||
```powershell
|
||
Unblock-File .\sanctum.exe
|
||
```
|
||
|
||
### Windows Defender "Überwachter Ordnerzugriff" (Controlled Folder Access - CFA)
|
||
Ist der erweiterte Ransomware-Schutz von Windows aktiv, kann Defender den Schreibzugriff auf Containerdateien in Standard-Benutzerordnern (`Dokumente`, `Desktop`) mit Fehler 5 (*Zugriff verweigert*) blockieren:
|
||
- **Abhilfe:** Erlauben Sie `sanctum.exe` in den Windows-Sicherheitseinstellungen (*Viren- & Bedrohungsschutz* $\to$ *Ransomware-Schutz verwalten* $\to$ *App durch überwachten Ordnerzugriff zulassen*), oder speichern Sie Container in einem separaten Verzeichnis (z. B. `C:\Sanctum\`).
|
||
|
||
### I/O-Performance-Tuning
|
||
Windows Defender scannt standardmäßig jeden modifizierten 1-MB-Chunk in Echtzeit. Durch das Hinzufügen der Dateiendung `*.sanctum` zu den Defender-Ausschlüssen lässt sich der I/O-Durchsatz bei großen Kopiervorgängen um 30–50% steigern.
|
||
|
||
---
|
||
|
||
## 📦 Release Packaging & Distribution
|
||
|
||
Um ein Distributionspaket mit Release-Binary, Checksummen und Dokumentation zu bauen:
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\scripts\package-release.ps1
|
||
```
|
||
|
||
Erzeugt:
|
||
- `dist/sanctum-v0.6.0-windows-x86_64.zip` (Windows x86_64 ZIP)
|
||
- `dist/sanctum-v0.6.0-linux-x86_64.tar.gz` (Linux x86_64 musl static TAR.GZ via `package-release-linux.ps1`)
|
||
- `dist/SHA256SUMS.txt`
|
||
|
||
---
|
||
|
||
## ⚖️ Rechtliche Hinweise, Compliance & Exportkontrolle
|
||
|
||
- **Kryptografie-Exportkontrolle (EAR & EU Dual-Use)**:
|
||
Sanctum nutzt starke Kryptografie (AES-256-GCM, Argon2id). Da der Quellcode als freie Open-Source-Software jedermann unbeschränkt und unentgeltlich zur Verfügung steht, unterliegt er den Ausnahmetatbeständen gem. **15 C.F.R. § 742.15(b)** (US EAR) sowie der **General Software Note (GSN)** der Verordnung (EU) 2021/821.
|
||
- **Plausible Deniability & Herausgabepflichten**:
|
||
Sanctum bietet mit dem steganografischen Alibi-Carrier (Modell A) ein informationstheoretisches Modell für glaubhafte Abstreitbarkeit. Dies ist ein technischer Schutzmechanismus, kein juristisches Schutzschild. Die rechtliche Bewertung im Fall strafprozessualer Herausgabeanordnungen (*Key Disclosure*) hängt von der jeweiligen Jurisdiktion ab (z. B. Nemo-tenetur-Grundsatz in DACH vs. RIPA Section 49 im UK).
|
||
- **Datenschutz & Telemetrie-Freiheit (DSGVO / GDPR)**:
|
||
Sanctum arbeitet zu 100% offline und enthält keinerlei Code für Telemetrie, Analytics, Fehlerberichterstattung oder IP-Übertragungen (Art. 25 DSGVO *Privacy by Design*).
|
||
- **Haftungsbeschränkung (EU/DACH Recht)**:
|
||
Die Software wird als unentgeltliche FOSS-Software bereitgestellt. Gemäß **§ 521 BGB** (Schenkungsrecht) ist die Haftung des Entwicklers auf Vorsatz und grobe Fahrlässigkeit beschränkt. Der Anwender ist für die sichere Verwahrung von Schlüsseln und Backups selbst verantwortlich.
|
||
- Ausführliche rechtliche Erläuterungen finden sich in [`LEGAL.md`](LEGAL.md).
|
||
|
||
---
|
||
|
||
## 📄 Lizenz & Changelog
|
||
|
||
- Lizenziert unter der [MIT License](LICENSE).
|
||
- Vollständige Third-Party-Attributionen aller ~230 Abhängigkeiten (Apache-2.0, MIT, BSD, SQLite Public Domain) sind in [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md) dokumentiert.
|
||
- Ausführliche rechtliche Bestimmungen und Exportkontroll-Hinweise sind in [`LEGAL.md`](LEGAL.md) geregelt.
|
||
- Details zu allen Versionen und Änderungen findest du im [CHANGELOG.md](CHANGELOG.md).
|
||
|