gnupg_verify — Funktion · PHP-Referenz

Signatur

gnupg_verify(resource $identifier, string $text, string $signature, string &$plaintext = null): array|false

Beschreibung

gnupg_verify() prüft die kryptografische Signatur eines signierten Textes mithilfe des GnuPG-Schlüsselbunds. Die Funktion ist Teil der gnupg-PECL-Erweiterung und ermöglicht es, die Authentizität und Integrität von Nachrichten oder Dateien zu überprüfen, die mit einem privaten GPG-Schlüssel signiert wurden.

Die Funktion unterstützt sowohl detached signatures (separate Signaturdaten, die im Parameter $signature übergeben werden) als auch clearsigned oder vollständig signierte Texte. Bei detached Signaturen enthält $text die Originalnachricht, bei kombinierten Signaturen wird der Klartextinhalt optional in $plaintext zurückgeschrieben.

Der Rückgabewert ist ein Array mit Details zur Signatur, darunter Fingerabdruck des Signierschlüssels, Zeitstempel und Gültigkeitsstatus. Damit lässt sich prüfen, ob eine Signatur von einem bekannten, vertrauenswürdigen Schlüssel stammt und ob sie unverändert ist.

Typische Einsatzbereiche sind die Verifikation von signierten E-Mails, signierten Software-Paketen oder jeglichem Datenaustausch, bei dem die Absenderidentität und Datenintegrität sichergestellt werden muss.

Parameter

Name	Typ	Beschreibung
$identifier Pflicht	resource	Eine GnuPG-Ressource, die zuvor mit `gnupg_init()` erstellt wurde.
$text Pflicht	string	Der signierte Text oder, bei einer detached signature, die originale Klartextnachricht, deren Signatur geprüft werden soll.
$signature Pflicht	string	Die zu prüfende Signatur. Bei einer detached signature wird die Signatur als separater String übergeben. Handelt es sich um eine kombinierte (nicht-detached) Signatur, muss dieser Parameter ein leerer String (`''`) oder `false` sein.
$plaintext	string	Optionale Referenz-Variable, in die der extrahierte Klartext geschrieben wird. Wird nur bei kombinierten Signaturen befüllt, wenn kein separater `$signature`-Parameter übergeben wurde.

Rückgabewert

Typ

array|false

Beschreibung

Bei Erfolg wird ein Array von Arrays zurückgegeben, wobei jedes innere Array Informationen zu einer gefundenen Signatur enthält:

fingerprint: Der vollständige Fingerabdruck des Signierschlüssels (String).
validity: Gültigkeitsstatus der Signatur (Integer, z. B. 0 = unbekannt, positive Werte = gültig).
timestamp: Unix-Zeitstempel des Signiervorgangs.
status: Statuscode der Verifikation (Integer).
summary: Zusammenfassung als Bitfeld (Integer).

Gibt false zurück, wenn die Verifikation fehlschlägt oder ein Fehler auftritt.

Beispiele

Detached Signature verifizieren

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

// Originalnachricht
$text = 'Dies ist eine wichtige Nachricht.';

// Bereits vorhandene detached Signatur (Base64-codiert oder binär)
$signature = file_get_contents('/pfad/zur/nachricht.sig');

// Signatur prüfen
$result = gnupg_verify($gpg, $text, $signature);

if ($result !== false) {
    foreach ($result as $sig) {
        echo 'Fingerabdruck: ' . $sig['fingerprint'] . PHP_EOL;
        echo 'Zeitstempel:   ' . date('Y-m-d H:i:s', $sig['timestamp']) . PHP_EOL;
        echo 'Gültigkeitsstatus: ' . $sig['validity'] . PHP_EOL;
    }
} else {
    echo 'Signaturprüfung fehlgeschlagen: ' . gnupg_geterror($gpg);
}

Fingerabdruck: ABCDEF1234567890ABCDEF1234567890ABCDEF12 Zeitstempel: 2024-03-15 10:23:45 Gültigkeitsstatus: 3

Kombinierte (clearsigned) Signatur verifizieren

<?php
$gpg = gnupg_init();

// Vollständig signierter Text (z. B. PGP SIGNED MESSAGE-Block)
$signedText = file_get_contents('/pfad/zur/nachricht.asc');

// Für kombinierte Signaturen: $signature als leeren String oder false übergeben
$plaintext = '';
$result = gnupg_verify($gpg, $signedText, false, $plaintext);

if ($result !== false) {
    echo 'Signatur gültig!' . PHP_EOL;
    echo 'Extrahierter Klartext: ' . trim($plaintext) . PHP_EOL;
    echo 'Signiert von: ' . $result[0]['fingerprint'] . PHP_EOL;
} else {
    echo 'Ungültige Signatur: ' . gnupg_geterror($gpg);
}

Signatur gültig! Extrahierter Klartext: Dies ist eine wichtige Nachricht. Signiert von: ABCDEF1234567890ABCDEF1234567890ABCDEF12

// Wichtig · Fallstricke

Voraussetzungen: Die gnupg-PECL-Erweiterung muss installiert und der öffentliche Schlüssel des Signierers im GPG-Schlüsselbund des laufenden Prozesses (bzw. des konfigurierten Homeverzeichnisses) vorhanden sein. Ist der Schlüssel nicht importiert, kann die Signatur nicht verifiziert werden und die Funktion gibt false zurück.

Sicherheitshinweis: Ein positiver Rückgabewert bedeutet nicht zwingend, dass dem Schlüssel vertraut wird. Prüfe zusätzlich das Feld validity (bzw. summary), um sicherzustellen, dass der Schlüssel im Schlüsselbund als vertrauenswürdig markiert ist. Ein unbekannter oder nicht vertrauenswürdiger Schlüssel kann trotzdem eine technisch korrekte Signatur erzeugen.

Fehlerbehandlung: Bei einem Fehler kann die Fehlermeldung mit gnupg_geterror($identifier) abgerufen werden.

Homeverzeichnis: Das GnuPG-Homeverzeichnis (wo Schlüssel gespeichert werden) kann beim Initialisieren mit gnupg_init() über den Parameter homedir gesetzt werden, um vom Standard-Verzeichnis abweichende Schlüsselbunde zu nutzen.

Siehe auch

gnupg_init gnupg_sign gnupg_encrypt gnupg_decrypt gnupg_import gnupg_geterror gnupg_addsignkey