PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/d-guides/encrypt-env-secrets.md
ValueOn AG 244726a716 upd
2026-06-02 09:42:12 +02:00

7 KiB
Raw Blame History

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

Diese Anleitung beschreibt, wie das PowerOn-Gateway-Tool scripts/script_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 platform-core 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. platform-core), 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 encryptValue aus modules/shared/configuration.py. Stellen Sie sicher, dass dieser Pfad importierbar ist (Start im Gateway-Verzeichnis oder PYTHONPATH setzen). Das Script fuegt platform-core automatisch zu sys.path hinzu.

Vorbedingungen

  1. requirements.txt im Projekt (Minimalbeispiel):

    cryptography>=41.0.0

    Falls Sie das Tool im bestehenden Gateway verwenden, nutzen Sie stattdessen die dortige Datei platform-core/requirements.txt.

  2. Notwendige Gateway-Komponenten (sofern außerhalb von platform-core verwendet):

    • modules/shared/configuration.py (liefert APP_CONFIG, _getMasterKey, encryptValue, decryptValue)
    • 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>

  3. Struktur/Importpfade sicherstellen:

    • Entweder das Tool im Ordner ausführen, der die modules-Struktur enthält (z. B. platform-core).
    • 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:

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

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

  3. 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: platform-core/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 den umgebungsspezifischen Prefix, z.B. DEV_ENC:<payload>, INT_ENC:<payload>, PROD_ENC:<payload> (abhaengig von APP_ENV_TYPE).
    • 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: platform-core/modules/shared/configuration.py (_get_master_key, _derive_encryption_key, encrypt_value).
  • Batch-Tool: platform-core/tool_security_encrypt_all_env_files.py (encrypt_all_secrets_in_file, process_all_env_files).