wiki/appdoc/doc_admin_encrypt_env_secret.md at 996f4f055abd1786dc6c7776ee33eaa04cd9b70c

ValueOn AG d9d13dfc12 fix: refactored structure and removed mandates data

2025-11-11 19:16:25 +01:00

6.8 KiB

Raw Blame History

Admin-Leitfaden: *_SECRET-Werte in Env-Dateien verschlüsseln

Diese Anleitung beschreibt, wie das PowerOn-Gateway-Tool tool_security_encrypt_all_env_files.py alle unverschlüsselten *_SECRET-Variablen in env_dev.env, env_int.env und env_prod.env verschlüsselt.

1) Einsatz in beliebigen Repositories & Voraussetzungen

Das Tool kann in jedem Repository eingesetzt werden, sofern die untenstehenden Vorbedingungen erfüllt sind. Standardmäßig ist es im Ordner gateway integriert und erwartet dort seine Abhängigkeiten. In anderen Repos müssen Sie die Gateway-Komponenten bereitstellen oder den PYTHONPATH entsprechend setzen.

Ausführungspfad: Entweder im Verzeichnis, das die Gateway-Module modules/shared enthält (z. B. gateway), oder mit gesetztem PYTHONPATH, sodass modules/shared/configuration.py importiert werden kann.
Python: Python 3.10+ mit Abhängigkeiten (siehe Kapitel „Vorbedingungen“). Installation z. B.:
- Windows PowerShell im Repo-Root: python -m venv .venv && .\.venv\Scripts\Activate.ps1
- pip install -r requirements.txt
Dateien:
- Eine config.ini (im gleichen Projektteil wie die modules), die zumindest APP_ENV_TYPE und APP_KEY_SYSVAR enthält.
- Die zu verarbeitenden Env-Dateien: env_dev.env, env_int.env, env_prod.env (oder eine Teilmenge via --files).
Rechte: Schreibrechte auf die Env-Dateien, Leserechte auf die Masterkey-Quelle (siehe Punkt 2).

Hinweis: Das Tool importiert encrypt_value aus modules/shared/configuration.py. Stellen Sie sicher, dass dieser Pfad importierbar ist (Start im Gateway-Verzeichnis oder PYTHONPATH setzen).

Vorbedingungen

requirements.txt im Projekt (Minimalbeispiel):
```
cryptography>=42.0.0
```
Falls Sie das Tool im bestehenden Gateway verwenden, nutzen Sie stattdessen die dortige Datei gateway/requirements.txt.
Notwendige Gateway-Komponenten (sofern außerhalb von gateway verwendet):
- modules/shared/configuration.py (liefert APP_CONFIG, _get_master_key, encrypt_value, decrypt_value)
- Optional, aber unterstützt: modules/shared/auditLogger.py (Audit-Events; Ausfall ist toleriert)
- config.ini im gleichen Baum wie modules, mit mindestens:
  - APP_ENV_TYPE = dev|int|prod (kann pro Env-Datei zusätzlich gesetzt werden)
  - APP_KEY_SYSVAR = <OS_ENV_NAME|Pfad_zur_Keydatei>
Struktur/Importpfade sicherstellen:
- Entweder das Tool im Ordner ausführen, der die modules-Struktur enthält (z. B. gateway).
- Oder PYTHONPATH so setzen, dass modules auflösbar ist, z. B. PowerShell:
```
$env:PYTHONPATH = (Resolve-Path .) 
python tool_security_encrypt_all_env_files.py --dry-run
```

2) Masterkey: Herkunft pro Umgebung

Die Verschlüsselung verwendet pro Umgebung einen Masterkey, der in modules/shared/configuration.py über _get_master_key(env_type) ermittelt wird. Quelle des Keys:

APP_KEY_SYSVAR (aus config.ini oder .env) gibt entweder
- den Namen einer OS-Umgebungsvariablen an, die den Masterkey direkt enthält, oder
- einen Dateipfad zu einer Key-Datei an.
Auflösung in dieser Reihenfolge:
- Wenn eine OS-Umgebungsvariable mit dem Namen APP_KEY_SYSVAR existiert, wird deren Wert direkt als Masterkey verwendet.
- Wenn keine OS-Variable gefunden wird, wird der Wert als Pfad interpretiert. Existiert die Datei, wird sie gelesen. Erwartetes Format je Zeile: env = key, z. B.:
  - dev = <masterkey_dev>
  - int = <masterkey_int>
  - prod = <masterkey_prod> Für die Zielumgebung (z. B. prod) wird die passend benannte Zeile verwendet.
Der abgeleitete Key wird per PBKDF2 in einen 32-Byte-Schlüssel umgewandelt und für Fernet genutzt. Der verschlüsselte Wert erhält ein Präfix gemäß Umgebung: DEV_ENC:, INT_ENC:, PROD_ENC: (weitere unterstützt: TEST_ENC:, STAGING_ENC:).

Wichtig: Die Umgebung für die Verschlüsselung wird pro Datei aus der jeweiligen Datei selbst gelesen (APP_ENV_TYPE=<dev|int|prod>). D. h. env_prod.env wird mit prod-Key verschlüsselt, unabhängig von der aktuellen Prozess-Umgebung.

3) Anwendung und Verhalten

Tool: gateway/tool_security_encrypt_all_env_files.py

Standardlauf (alle drei Dateien, mit Backup):
```
python tool_security_encrypt_all_env_files.py
```
Wirkung:
- Liest je Datei APP_ENV_TYPE.
- Findet alle Schlüssel, deren Name auf _SECRET endet, und deren Werte noch kein *_ENC:-Präfix haben.
- Unterstützt einzeilige und mehrzeilige JSON-Werte (Klammer-Auf/Zu wird erkannt).
- Verschlüsselt die Werte mit dem passenden Umgebungs-Key und ersetzt die Originalwerte in der Datei durch ENV_ENC:<payload>.
- Legt vor Änderungen eine Backup-Datei mit Zeitstempel neben der Originaldatei an, z. B. env_prod.env.20251015_101530.backup.
Trockenlauf (nur anzeigen, nichts schreiben):
```
python tool_security_encrypt_all_env_files.py --dry-run
```
Wirkung: Listet, welche Zeilen/Keys verschlüsselt würden. Es werden keine Änderungen vorgenommen und keine Backups erstellt.
Ohne Backups ausführen:
```
python tool_security_encrypt_all_env_files.py --no-backup
```
Wirkung: Schreibt Änderungen ohne vorherige Backup-Datei.

Nur bestimmte Dateien verarbeiten:

python tool_security_encrypt_all_env_files.py --files env_dev.env env_prod.env

Ausgabe/Ergebnis:

Pro Datei: Anzahl gefundener Secrets, Anzahl verschlüsselter Secrets, ggf. Backup-Datei, Fehler.
Zusammenfassung am Ende über alle verarbeiteten Dateien.

Was wird als „bereits verschlüsselt“ erkannt?

Alle Werte, die mit einem der Präfixe beginnen: DEV_ENC:, INT_ENC:, PROD_ENC:, TEST_ENC:, STAGING_ENC:. Diese werden übersprungen.

Fehlerbilder und Checks:

Fehlt APP_KEY_SYSVAR in config.ini/.env oder zeigt er auf eine nicht existierende OS-Variable/Datei, schlägt die Verschlüsselung fehl.
Fehlt in einer Key-Datei der passende Eintrag für die Zielumgebung, wird ein Fehler gemeldet.
Schreibfehler (z. B. fehlende Rechte) verhindern das Aktualisieren der Env-Datei.

Best Practices

Änderungen zuerst mit --dry-run prüfen.
Vor Produktivläufen sicherstellen, dass APP_KEY_SYSVAR korrekt auf OS-Variable oder Key-Datei zeigt und die Datei einen Eintrag für die Zielumgebung enthält.
Backups beibehalten, um bei Bedarf Änderungen zurückzurollen.
JSON-Secrets in Env-Dateien korrekt mit { ... } kapseln; das Tool erkennt und ersetzt mehrzeilige JSON-Blöcke vollständig.

Referenz

Schlüsselauflösung und Verschlüsselung: gateway/modules/shared/configuration.py (_get_master_key, _derive_encryption_key, encrypt_value).
Batch-Tool: gateway/tool_security_encrypt_all_env_files.py (encrypt_all_secrets_in_file, process_all_env_files).

6.8 KiB Raw Blame History