openssl_password_hash — Funktion · PHP-Referenz

Signatur

openssl_password_hash(string $algo, string $password, array $options = []): string|false

Beschreibung

openssl_password_hash() ist eine OpenSSL-basierte Alternative zu password_hash() für die Argon2-Algorithmen. Sie nutzt direkt die OpenSSL-Bibliothek statt libsodium oder der internen PHP-Implementierung, um Argon2i- bzw. Argon2id-Hashes zu erzeugen. Die Funktion gibt einen Hash im PHC-Format (Password Hashing Competition String Format) zurück, der mit openssl_password_verify() verifiziert werden kann.

Argon2id wird als Standardwahl empfohlen, da es sowohl gegen GPU-Angriffe als auch gegen Seitenkanalangriffe robuster ist als Argon2i. Über den $options-Parameter lassen sich Speicher, Zeitaufwand und Parallelitätsgrad feinsteuern, um den Hash an die Leistungsfähigkeit des Zielsystems anzupassen.

Diese Funktion ist besonders dann sinnvoll, wenn in einer Umgebung bewusst auf OpenSSL als kryptografisches Backend gesetzt wird (z. B. wenn libsodium nicht verfügbar ist) oder wenn man explizit die OpenSSL-Implementierung von Argon2 nutzen möchte. Die zurückgegebenen Hashes sind kompatibel mit dem PHC-Format und können systemübergreifend ausgetauscht werden.

Die Funktion erfordert, dass PHP mit OpenSSL-Unterstützung kompiliert wurde und OpenSSL ≥ 3.2 vorhanden ist, da ältere Versionen Argon2 nicht nativ unterstützen.

Parameter

Name	Typ	Default	Beschreibung
$algo Pflicht	string		Der zu verwendende Algorithmus. Erlaubte Werte sind `PASSWORD_ARGON2I` (entspricht dem String `'argon2i'`) und `PASSWORD_ARGON2ID` (entspricht `'argon2id'`). Argon2id wird für neue Implementierungen empfohlen.
$password Pflicht	string		Das Klartext-Passwort, das gehasht werden soll. Es gibt keine explizite Längenbeschränkung, aber extrem lange Passwörter können den Rechenaufwand erhöhen.
$options	array	[]	Optionales Array zur Feinsteuerung des Hash-Prozesses. Unterstützte Schlüssel: `memory_cost` (Speicher in KiB, Standard: `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`), `time_cost` (Iterationen, Standard: `PASSWORD_ARGON2_DEFAULT_TIME_COST`), `threads` (Parallelitätsgrad, Standard: `PASSWORD_ARGON2_DEFAULT_THREADS`).

Rückgabewert

Typ

string|false

Beschreibung

Gibt bei Erfolg den erzeugten Passwort-Hash als PHC-Format-String zurück. Bei einem Fehler (z. B. ungültiger Algorithmus, fehlende OpenSSL-Unterstützung) wird false zurückgegeben.

Beispiele

Einfaches Hashen eines Passworts mit Argon2id

<?php
// Passwort mit Argon2id hashen (empfohlener Algorithmus)
$password = 'meinSicheresPasswort123!';
$hash = openssl_password_hash(PASSWORD_ARGON2ID, $password);

if ($hash === false) {
    echo 'Fehler beim Erzeugen des Hashes.';
} else {
    echo 'Hash: ' . $hash . PHP_EOL;
    // Beispielausgabe: $argon2id$v=19$m=65536,t=4,p=1$...
}

Hash: $argon2id$v=19$m=65536,t=4,p=1$<salt>$<hash>

Hashen mit eigenen Kostenfaktoren und anschließende Verifikation

<?php
$password = 'geheimesPasswort';

// Benutzerdefinierte Kostenfaktoren für höhere Sicherheit
$options = [
    'memory_cost' => 131072, // 128 MiB
    'time_cost'   => 6,
    'threads'     => 2,
];

$hash = openssl_password_hash(PASSWORD_ARGON2ID, $password, $options);

if ($hash === false) {
    die('Hash-Erzeugung fehlgeschlagen.');
}

echo 'Erzeugter Hash: ' . $hash . PHP_EOL;

// Verifikation des Passworts gegen den Hash
if (openssl_password_verify($password, $hash)) {
    echo 'Passwort korrekt!';
} else {
    echo 'Passwort falsch!';
}

Erzeugter Hash: $argon2id$v=19$m=131072,t=6,p=2$<salt>$<hash> Passwort korrekt!

Verwendung von Argon2i statt Argon2id

<?php
$password = 'legacyPasswort';

// Argon2i für Systeme, die Argon2id nicht unterstützen
$hash = openssl_password_hash(PASSWORD_ARGON2I, $password);

if ($hash !== false) {
    echo 'Argon2i-Hash erzeugt: ' . $hash . PHP_EOL;
    var_dump(openssl_password_verify($password, $hash));
}

Argon2i-Hash erzeugt: $argon2i$v=19$m=65536,t=4,p=1$<salt>$<hash> bool(true)

// Wichtig · Fallstricke

Sicherheitshinweis: Verwende niemals einfache Hash-Funktionen wie md5() oder sha1() für Passwörter. openssl_password_hash() mit Argon2id ist die empfohlene Methode, wenn OpenSSL als kryptografisches Backend eingesetzt wird.

Verfügbarkeit: Diese Funktion ist erst ab PHP 8.4.0 verfügbar und erfordert OpenSSL ≥ 3.2. Prüfe vor dem Einsatz, ob die Funktion mit function_exists('openssl_password_hash') verfügbar ist.

Rückgabe prüfen: Der Rückgabewert sollte immer auf false geprüft werden, bevor der Hash gespeichert wird, um fehlerhafte oder leere Hashes in der Datenbank zu vermeiden.

Kostenfaktoren anpassen: Die Standardwerte sind als Ausgangspunkt gedacht. Passe memory_cost und time_cost so an, dass das Hashen auf dem Zielsystem etwa 100–500 ms dauert, um Brute-Force-Angriffe effektiv zu erschweren, ohne legitime Nutzer zu beeinträchtigen.

Siehe auch

openssl_password_verify openssl_password_needs_rehash password_hash password_verify password_needs_rehash PASSWORD_ARGON2ID PASSWORD_ARGON2I