openssl_x509_fingerprint — Funktion · PHP-Referenz

Signatur

openssl_x509_fingerprint(OpenSSLCertificate|string $certificate, string $digest_algo = "sha1", bool $binary = false): string|false

Beschreibung

openssl_x509_fingerprint() erzeugt einen Hash-Wert (Fingerabdruck) für ein übergebenes X.509-Zertifikat. Damit lässt sich die Identität eines Zertifikats eindeutig und kompakt prüfen, ohne das vollständige Zertifikat vergleichen zu müssen. Typische Anwendungsfälle sind die Verifizierung von TLS-Zertifikaten, Certificate-Pinning oder die Überprüfung gespeicherter Zertifikat-Hashes in Datenbanken.

Als Digest-Algorithmus kann jeder von OpenSSL unterstützte Algorithmus verwendet werden, z. B. sha1, sha256, sha384 oder md5. Der Standard ist sha1, jedoch empfiehlt sich für neue Anwendungen mindestens sha256, da SHA-1 als kryptografisch schwach gilt.

Das Ergebnis ist standardmäßig eine hexadezimal kodierte Zeichenkette (Kleinbuchstaben, ohne Trennzeichen). Wird der Parameter binary auf true gesetzt, wird der rohe Binär-Hash zurückgegeben, was sich z. B. für die Base64-Kodierung oder den direkten Binärvergleich eignet.

Das Zertifikat kann entweder als OpenSSLCertificate-Ressource (ab PHP 8.0) oder als PEM-kodierter String übergeben werden. Im Fehlerfall – etwa bei einem ungültigen Zertifikat – gibt die Funktion false zurück.

Parameter

Name	Typ	Default	Beschreibung
$certificate Pflicht	OpenSSLCertificate\|string		Das X.509-Zertifikat, dessen Fingerabdruck berechnet werden soll. Kann ein `OpenSSLCertificate`-Objekt (PHP >= 8.0) oder ein PEM-kodierter Zertifikat-String sein.
$digest_algo	string	sha1	Der zu verwendende Digest-Algorithmus, z. B. `"sha1"`, `"sha256"` oder `"md5"`. Für sicherheitskritische Anwendungen sollte mindestens `"sha256"` gewählt werden.
$binary	bool	false	Legt das Ausgabeformat fest. Bei `false` (Standard) wird eine hexadezimal kodierte Zeichenkette zurückgegeben. Bei `true` wird der rohe Binär-Hash zurückgegeben.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den Fingerabdruck des Zertifikats als hexadezimal kodierte Zeichenkette (oder als Binär-String, falls binary = true) zurück. Im Fehlerfall – z. B. bei ungültigem Zertifikat oder unbekanntem Algorithmus – wird false zurückgegeben.

Beispiele

SHA-256-Fingerabdruck eines PEM-Zertifikats berechnen

<?php
// PEM-Zertifikat einlesen (z. B. aus einer Datei)
$pem = file_get_contents('/etc/ssl/certs/example.pem');

// Fingerabdruck mit SHA-256 berechnen
$fingerprint = openssl_x509_fingerprint($pem, 'sha256');

if ($fingerprint !== false) {
    echo 'SHA-256-Fingerabdruck: ' . $fingerprint . PHP_EOL;
} else {
    echo 'Fehler: Ungültiges Zertifikat oder unbekannter Algorithmus.' . PHP_EOL;
}

SHA-256-Fingerabdruck: 3c4b1e7a2d9f8c6a1b5e4d3f2a9c7b8e0d1f2a3c4b5e6d7f8a9b0c1d2e3f4a5b

Certificate Pinning: Zertifikat gegen gespeicherten Fingerabdruck prüfen

<?php
// Bekannter, vertrauenswürdiger Fingerabdruck (z. B. aus der Konfiguration)
$trustedFingerprint = '3c4b1e7a2d9f8c6a1b5e4d3f2a9c7b8e0d1f2a3c4b5e6d7f8a9b0c1d2e3f4a5b';

// Aktuelles Zertifikat laden
$pem = file_get_contents('/etc/ssl/certs/example.pem');
$cert = openssl_x509_read($pem);

if ($cert === false) {
    die('Zertifikat konnte nicht gelesen werden.');
}

$currentFingerprint = openssl_x509_fingerprint($cert, 'sha256');

if (hash_equals($trustedFingerprint, $currentFingerprint)) {
    echo 'Zertifikat ist vertrauenswürdig.' . PHP_EOL;
} else {
    echo 'WARNUNG: Zertifikat stimmt nicht mit dem bekannten Fingerabdruck überein!' . PHP_EOL;
}

Zertifikat ist vertrauenswürdig.

Binären Fingerabdruck für Base64-Ausgabe verwenden

<?php
$pem = file_get_contents('/etc/ssl/certs/example.pem');

// Binären Fingerabdruck berechnen und Base64-kodieren
$binaryFingerprint = openssl_x509_fingerprint($pem, 'sha256', true);

if ($binaryFingerprint !== false) {
    $base64Fingerprint = base64_encode($binaryFingerprint);
    echo 'Base64-Fingerabdruck: ' . $base64Fingerprint . PHP_EOL;
}

Base64-Fingerabdruck: PEsee...

// Wichtig · Fallstricke

SHA-1 ist veraltet: Der Standardalgorithmus sha1 gilt als kryptografisch unsicher und sollte in neuen Anwendungen nicht mehr verwendet werden. Für sicherheitskritische Anwendungen empfiehlt sich sha256 oder stärker.

Timing-sichere Vergleiche: Beim Vergleichen von Fingerabdrücken sollte stets hash_equals() statt dem Gleichheitsoperator === verwendet werden, um Timing-Angriffe zu vermeiden.

PHP 8.0-Änderung: Ab PHP 8.0 gibt openssl_x509_read() ein OpenSSLCertificate-Objekt statt einer Ressource zurück. openssl_x509_fingerprint() akzeptiert beide Typen.

Verfügbare Algorithmen: Eine Liste der unterstützten Digest-Algorithmen liefert openssl_get_md_methods().

Siehe auch

openssl_x509_read openssl_x509_parse openssl_x509_verify openssl_get_md_methods hash_equals openssl_digest