gnupg_decryptverify — Funktion · PHP-Referenz

Signatur

gnupg_decryptverify(resource $identifier, string $text, array &$plaintext): array|false

Beschreibung

gnupg_decryptverify() kombiniert die Operationen der Entschlüsselung und Signaturverifizierung in einem einzigen Schritt. Die Funktion erwartet einen mit GnuPG verschlüsselten (und optional signierten) Text, entschlüsselt diesen mithilfe des konfigurierten privaten Schlüssels und prüft gleichzeitig, ob eine gültige Signatur vorhanden ist. Der entschlüsselte Klartext wird über den Per-Referenz-Parameter $plaintext zurückgegeben.

Die Funktion ist dann sinnvoll, wenn sichere Kommunikation sowohl Vertraulichkeit (Verschlüsselung) als auch Authentizität (Signatur) erfordert – typischerweise in E-Mail-Verschlüsselungssystemen (OpenPGP) oder sicheren Datei-Übertragungen. Vor dem Aufruf muss mit gnupg_adddecryptkey() ein geeigneter privater Schlüssel mit Passphrase registriert werden.

Der Rückgabewert ist ein Array mit Informationen über die gefundenen Signaturen, ähnlich wie bei gnupg_verify(). Jedes Element enthält Details zum Fingerabdruck des Signierers, den Zeitstempel, den Gültigkeitsstatus sowie eventuelle Fehlerflags. Enthält die Nachricht keine Signatur, wird ein leeres Array zurückgegeben. Bei einem Fehler gibt die Funktion false zurück.

Achtung: Der zu entschlüsselnde Text muss im ASCII-Armor-Format oder als Binärdaten vorliegen, die von GnuPG erzeugt wurden. Fehlende oder falsch konfigurierte Schlüssel führen zu einem Fehler, der über gnupg_geterror() abgerufen werden kann.

Parameter

Name	Typ	Beschreibung
$identifier Pflicht	resource	Ein gültiges GnuPG-Ressourcen-Handle, das zuvor mit `gnupg_init()` erzeugt wurde.
$text Pflicht	string	Der verschlüsselte (und ggf. signierte) Text im ASCII-Armor-Format oder als GnuPG-Binärdaten, der entschlüsselt und verifiziert werden soll.
$plaintext Pflicht	string	Wird per Referenz übergeben und enthält nach dem Funktionsaufruf den entschlüsselten Klartext. Vor dem Aufruf muss die Variable deklariert oder initialisiert sein (z. B. als leerer String).

Rückgabewert

Typ

array|false

Beschreibung

Gibt bei Erfolg ein Array zurück, dessen Elemente jeweils ein assoziatives Array mit folgenden Schlüsseln enthalten:

fingerprint – Fingerabdruck des Signierschlüssels
validity – Gültigkeit der Signatur als Integer-Konstante
timestamp – Unix-Zeitstempel der Signatur
status – Status-Flag der Signatur
summary – Zusammenfassung als Bitmaske

Enthält die Nachricht keine Signatur, wird ein leeres Array zurückgegeben. Bei einem Fehler (z. B. kein passender Schlüssel, ungültige Eingabe) gibt die Funktion false zurück.

Beispiele

Einfaches Entschlüsseln und Verifizieren einer signierten Nachricht

<?php
// GnuPG-Ressource initialisieren
$gpg = gnupg_init();

// Privaten Schlüssel für Entschlüsselung registrieren
// Fingerabdruck und Passphrase entsprechend anpassen
$fingerprint = 'ABCDEF1234567890ABCDEF1234567890ABCDEF12';
gnupg_adddecryptkey($gpg, $fingerprint, 'meine_passphrase');

// Verschlüsselte und signierte Nachricht (ASCII-Armor)
$encryptedText = '-----BEGIN PGP MESSAGE-----
...
-----END PGP MESSAGE-----';

$plaintext = '';
$result = gnupg_decryptverify($gpg, $encryptedText, $plaintext);

if ($result === false) {
    echo 'Fehler: ' . gnupg_geterror($gpg);
} else {
    echo 'Klartext: ' . $plaintext . PHP_EOL;

    if (empty($result)) {
        echo 'Keine Signatur gefunden.' . PHP_EOL;
    } else {
        foreach ($result as $sig) {
            echo 'Fingerabdruck: ' . $sig['fingerprint'] . PHP_EOL;
            echo 'Gültigkeit:   ' . $sig['validity'] . PHP_EOL;
            echo 'Zeitstempel:  ' . date('Y-m-d H:i:s', $sig['timestamp']) . PHP_EOL;
        }
    }
}
?>

Klartext: Hallo, das ist eine geheime Nachricht! Fingerabdruck: ABCDEF1234567890ABCDEF1234567890ABCDEF12 Gültigkeit: 3 Zeitstempel: 2024-01-15 10:30:00

Fehlerbehandlung bei fehlendem Schlüssel

<?php
$gpg = gnupg_init();

// Kein Schlüssel registriert — Entschlüsselung schlägt fehl
$encryptedText = '-----BEGIN PGP MESSAGE-----
...
-----END PGP MESSAGE-----';

$plaintext = '';
$result = gnupg_decryptverify($gpg, $encryptedText, $plaintext);

if ($result === false) {
    // Fehler auslesen und protokollieren
    $error = gnupg_geterror($gpg);
    error_log('GnuPG-Fehler: ' . $error);
    echo 'Entschlüsselung fehlgeschlagen: ' . htmlspecialchars($error, ENT_QUOTES, 'UTF-8');
} else {
    echo 'Erfolg';
}
?>

Entschlüsselung fehlgeschlagen: decryption failed

// Wichtig · Fallstricke

Sicherheitshinweise:

Passphrasen für private Schlüssel sollten niemals im Quellcode hartcodiert werden. Verwende stattdessen Umgebungsvariablen oder sichere Konfigurationsdateien mit eingeschränkten Dateisystem-Rechten.
Ein leeres Ergebnis-Array bedeutet, dass die Nachricht zwar erfolgreich entschlüsselt, aber nicht signiert war. Dies sollte in sicherheitskritischen Anwendungen explizit geprüft und ggf. abgelehnt werden.
Die Funktion gehört zur gnupg-PECL-Erweiterung und muss separat installiert sowie in der php.ini aktiviert werden (extension=gnupg).
Der Homeverzeichnis-Pfad des GnuPG-Schlüsselbunds (GNUPGHOME) muss für den Webserver-Prozess lesbar sein. Dies kann zu Berechtigungsproblemen führen, wenn der Schlüsselbund im Home-Verzeichnis eines anderen Benutzers liegt.
Gib entschlüsselte Klartexte niemals ungefiltert an den Browser aus — schütze dich vor XSS mittels htmlspecialchars().

Siehe auch

gnupg_init gnupg_adddecryptkey gnupg_decrypt gnupg_verify gnupg_encryptsign gnupg_geterror