Secrets Management in PHP Anwendungen

1. Warum Secrets Management mehr ist als .env verstecken

Secrets Management beschreibt den vollständigen Lebenszyklus von Zugangsdaten: Erzeugung, Speicherung, Verteilung an Anwendungen, Rotation und schließlich Widerruf. In vielen PHP-Projekten beschränkt sich Secrets Management darauf, eine .env-Datei in die .gitignore aufzunehmen und zu hoffen, dass niemand sie versehentlich committet. Das ist ein Anfang, aber kein vollständiges Secrets Management, weil es weder Verschlüsselung im Ruhezustand noch eine Rotationsstrategie noch eine zentrale Zugriffskontrolle abdeckt.

Der Unterschied wird sichtbar, sobald ein Secret kompromittiert wird. Ohne durchdachtes Secrets Management bedeutet ein geleaktes Datenbank-Passwort oft: Alle Server manuell durchgehen, jede Konfigurationsdatei anpassen, hoffen, dass keine Kopie übersehen wird. Mit etabliertem Secrets Management ist die Rotation ein einzelner Befehl, weil es genau eine Quelle der Wahrheit für jedes Secret gibt, aus der alle Anwendungsinstanzen zur Laufzeit lesen.

2. Umgebungsvariablen als erste Stufe des Secrets Management

Der Einstieg in solides Secrets Management ist die konsequente Trennung von Code und Konfiguration über Umgebungsvariablen. Die .env-Datei enthält niemals fest kodierte Werte im Code, sondern wird zur Laufzeit von einer Bibliothek wie vlucas/phpdotenv eingelesen und über getenv() oder $_ENV zur Verfügung gestellt. Wichtig für sauberes Secrets Management: Die .env-Datei selbst gehört niemals ins Versionskontrollsystem, nur eine .env.example mit Platzhalterwerten dokumentiert, welche Variablen benötigt werden.

Ein häufig übersehener Aspekt bei Umgebungsvariablen ist, dass sie über phpinfo(), Prozesslisten anderer Nutzer auf demselben Host oder Debugging-Tools sichtbar sein können. Für striktes Secrets Management reicht die reine Umgebungsvariable deshalb bei hochsensiblen Werten wie Verschlüsselungsschlüsseln nicht aus, hier kommen die im nächsten Abschnitt beschriebenen Mechanismen zum Einsatz.

<?php

declare(strict_types=1);

use Dotenv\Dotenv;

require __DIR__ . '/vendor/autoload.php';

// Load .env only in local/dev — never ship it to production servers
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['DB_PASSWORD', 'API_SECRET_KEY'])->notEmpty();

final class Config
{
    public static function dbPassword(): string
    {
        $value = $_ENV['DB_PASSWORD'] ?? null;
        if ($value === null || $value === '') {
            throw new RuntimeException('DB_PASSWORD is not configured');
        }
        return $value;
    }
}

3. Verschlüsselung im Ruhezustand für sensible Konfigurationswerte

Für Secrets, die in einer Konfigurationsdatei oder Datenbank liegen müssen, ist Verschlüsselung im Ruhezustand die nächste Stufe im Secrets Management. PHP bietet mit der sodium-Erweiterung, seit PHP 7.2 fester Bestandteil des Kerns, moderne authentifizierte Verschlüsselung. Der Klartext wird mit einem Master-Schlüssel verschlüsselt, der selbst wiederum nicht im selben Repository liegt, sondern über eine Umgebungsvariable oder einen Schlüsseldienst bereitgestellt wird.

Der entscheidende Punkt bei diesem Ansatz im Secrets Management: Der Master-Schlüssel wird niemals mit den verschlüsselten Werten zusammen gespeichert. Liegt eine verschlüsselte Konfigurationsdatei im Repository, aber der Master-Schlüssel ausschließlich auf dem Produktionsserver, bleibt ein Repository-Leak folgenlos für die eigentlichen Zugangsdaten. Diese Trennung ist der Kern jeder ernsthaften Secrets Management-Strategie.

<?php

declare(strict_types=1);

final class SecretBox
{
    public function __construct(private readonly string $masterKeyBase64)
    {
    }

    /**
     * Encrypt a secret value at rest using libsodium authenticated encryption.
     */
    public function encrypt(string $plaintext): string
    {
        $key = sodium_base642bin($this->masterKeyBase64, SODIUM_BASE64_VARIANT_ORIGINAL);
        $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

        return base64_encode($nonce . $ciphertext);
    }

    /**
     * Decrypt a value produced by encrypt().
     */
    public function decrypt(string $encoded): string
    {
        $key = sodium_base642bin($this->masterKeyBase64, SODIUM_BASE64_VARIANT_ORIGINAL);
        $decoded = base64_decode($encoded, true);
        $nonce = substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
        $ciphertext = substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);

        $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
        if ($plaintext === false) {
            throw new RuntimeException('Secret decryption failed — key mismatch or tampered data');
        }
        return $plaintext;
    }
}

// Master key comes from an environment variable, never from the repository
$box = new SecretBox(getenv('SECRETS_MASTER_KEY'));
$stored = $box->encrypt('db-password-123');

4. Vault-Integration: Secrets zur Laufzeit abrufen

Ab einer gewissen Team- und Infrastrukturgröße wird lokale Verschlüsselung im Secrets Management durch einen dedizierten Secrets-Dienst wie HashiCorp Vault oder einen Cloud-eigenen Secrets Manager ergänzt. Der zentrale Vorteil: Secrets liegen an keiner Stelle im Anwendungscode oder in Konfigurationsdateien, sondern werden beim Anwendungsstart per authentifiziertem API-Aufruf abgerufen und ausschließlich im Arbeitsspeicher gehalten. Zugriffsrechte, Audit-Logs und automatische Ablaufzeiten kommen dabei serverseitig aus dem Vault selbst.

Für PHP-Anwendungen bedeutet das praktisch: Ein kleiner HTTP-Client spricht beim Bootstrap mit der Vault-API, authentifiziert sich mit einem kurzlebigen Token, zum Beispiel über Kubernetes-Service-Account-Tokens, und ruft die benötigten Secrets ab. Dieses Muster im Secrets Management reduziert die Angriffsfläche erheblich, weil kompromittierter Anwendungscode allein noch keinen dauerhaften Zugriff auf die Secrets liefert, wenn das Token kurzlebig und eng gescoped ist.

<?php

declare(strict_types=1);

final class VaultSecretClient
{
    public function __construct(
        private readonly string $vaultAddr,
        private readonly string $token,
    ) {
    }

    /**
     * Fetch a secret from Vault's KV v2 engine at request time.
     *
     * @return array<string, string>
     */
    public function read(string $path): array
    {
        $ch = curl_init(sprintf('%s/v1/secret/data/%s', $this->vaultAddr, $path));
        curl_setopt_array($ch, [
            CURLOPT_HTTPHEADER => ['X-Vault-Token: ' . $this->token],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 3,
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        /** @var array{data: array{data: array<string, string>}} $decoded */
        $decoded = json_decode($response ?: '', true, flags: JSON_THROW_ON_ERROR);
        return $decoded['data']['data'];
    }
}

$vault = new VaultSecretClient('https://vault.internal:8200', getenv('VAULT_TOKEN'));
$dbCredentials = $vault->read('database/production');

5. Rotation von Zugangsdaten ohne Ausfallzeiten

Rotation ist der Teil des Secrets Management, der am häufigsten vernachlässigt wird, weil er ohne konkreten Anlass wie einen Sicherheitsvorfall nie dringend erscheint. Dabei ist regelmäßige Rotation genau der Mechanismus, der ein Secret-Leak von einem dauerhaften Problem zu einem zeitlich begrenzten Fenster macht. Für Datenbank-Zugangsdaten bedeutet das: Ein neuer Nutzer mit neuem Passwort wird angelegt, die Anwendung stellt schrittweise auf die neuen Zugangsdaten um, erst danach wird der alte Nutzer deaktiviert.

Für unterbrechungsfreie Rotation im Secrets Management ist entscheidend, dass alte und neue Zugangsdaten für eine Übergangszeit parallel gültig sind. Dienste wie Vault unterstützen das mit dynamischen, zeitlich begrenzten Datenbank-Zugangsdaten direkt aus der Datenbank-Engine heraus, sodass jede Anwendungsinstanz automatisch eigene, kurzlebige Zugangsdaten erhält, statt sich ein einziges statisches Passwort mit allen anderen Instanzen zu teilen.

6. Secrets aus Logs und Fehlermeldungen fernhalten

Ein oft übersehener Kanal, über den Secrets aus dem Secrets Management ausbrechen, sind Logdateien und Fehlermeldungen. Eine unbedachte var_dump()-Ausgabe eines Konfigurationsobjekts, eine Exception mit dem kompletten Datenbank-DSN in der Stacktrace-Nachricht, oder ein API-Client, der Request-Header inklusive Authorization-Token mitloggt, unterlaufen jede noch so ausgefeilte Rotations- und Verschlüsselungsstrategie.

Der pragmatische Ansatz im Secrets Management: Eine zentrale Logging-Bibliothek maskiert bekannte Secret-Schlüssel automatisch, etwa durch eine Denylist von Feldnamen wie password, token oder secret, deren Werte vor dem Schreiben ins Log durch ***REDACTED*** ersetzt werden. Exception-Handler sollten außerdem nie die vollständige Exception-Message inklusive potenziell eingebetteter Zugangsdaten an den Client ausgeben, sondern nur eine generische Fehlermeldung, während die Details ausschließlich intern geloggt werden.

7. Secrets Management in CI/CD-Pipelines

Build- und Deployment-Pipelines sind ein weiterer kritischer Punkt im Secrets Management, weil sie fast immer Zugriff auf produktionsnahe Zugangsdaten brauchen, etwa für Datenbank-Migrationen oder Deployment-Ziele. Secrets gehören dabei in den verschlüsselten Secrets-Store der CI-Plattform, niemals als Klartext-Variable im Pipeline-Skript oder als Kommentar in einer Konfigurationsdatei.

Zusätzlich sollten Pipeline-Logs standardmäßig maskieren, wenn eine als Secret markierte Variable in der Ausgabe eines Befehls erscheint. Für nachhaltiges Secrets Management in CI/CD gilt zusätzlich: Jede Pipeline sollte nur Zugriff auf die Secrets bekommen, die sie tatsächlich für ihre eigene Stufe braucht, statt pauschal alle Produktions-Secrets für jeden Build-Job verfügbar zu machen.

8. Typische Fehler beim Secrets Management

Der häufigste Fehler ist das Committen der .env-Datei, meist versehentlich beim ersten Setup, bevor .gitignore korrekt konfiguriert wurde. Da Git-Historie dauerhaft ist, reicht ein nachträgliches Löschen der Datei nicht aus, das komplette Secret muss rotiert werden, sobald es einmal committet wurde. Ein zweiter Fehler im Secrets Management ist die Wiederverwendung desselben Secrets über mehrere Umgebungen hinweg, sodass ein Leak in der Staging-Umgebung automatisch auch die Produktion kompromittiert.

Ein dritter, subtilerer Fehler: Secrets werden zwar verschlüsselt gespeichert, aber der Entschlüsselungsschlüssel liegt neben der verschlüsselten Datei im selben Verzeichnis oder Repository. Das täuscht Sicherheit vor, bietet aber keinen echten Schutz, weil beide Teile gemeinsam kompromittiert werden. Konsequentes Secrets Management trennt Schlüssel und verschlüsselte Werte immer über unterschiedliche Zugriffspfade und im Idealfall unterschiedliche Systeme.

9. Speicherorte für Secrets im Vergleich

Je nach Reifegrad der Infrastruktur eignen sich unterschiedliche Speicherorte im Secrets Management unterschiedlich gut. Die folgende Übersicht ordnet die gängigen Optionen ein.

Die Tabelle zeigt einen klaren Trend im Secrets Management: Je zentraler und automatisierter Speicherung und Rotation ablaufen, desto geringer das Restrisiko bei einem Leak. Ein einzelner kompromittierter Prozess kann bei dynamischen, kurzlebigen Zugangsdaten kaum noch dauerhaften Schaden anrichten.

10. Zusammenfassung

Solides Secrets Management in PHP ist ein Stufenmodell: Umgebungsvariablen trennen Code und Konfiguration, Verschlüsselung im Ruhezustand schützt Werte, die dennoch gespeichert werden müssen, und eine Vault-Integration entfernt Secrets vollständig aus Code und Dateisystem zugunsten eines zentralen, auditierbaren Dienstes. Rotation macht ein einmaliges Leak zu einem zeitlich begrenzten Risiko statt zu einem dauerhaften Problem.

Am Ende zahlt sich Secrets Management genau dann aus, wenn etwas schiefgeht: Ein kompromittiertes Secret lässt sich in Minuten statt Tagen rotieren, weil es genau eine Quelle der Wahrheit gibt. Logs und Fehlermeldungen, die konsequent von Secrets bereinigt sind, verhindern zusätzlich, dass ein an sich harmloser Debugging-Vorgang zur eigentlichen Schwachstelle wird.

11. FAQ: Secrets Management in PHP Anwendungen