<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 5003a6ea92eb50ac92121782eedfc5ad3fe9d061 Maintainer: nobody Status: ready -->

<!-- Reviewed: yes -->

<!-- Rev-Revision: 79c06cc0e7872f1401a4c37dc9298b0bedb0dde4 Reviewer: samesch -->

<refentry xml:id="function.password-hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>password_hash</refname>

<refpurpose>Erstellt einen Passwort-Hash</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>password_hash</methodname>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>password</parameter></methodparam>

<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<para>

<function>password_hash</function> erstellt einen neuen Passwort-Hash und

benutzt dabei einen starken Einweg-Hashing-Algorithmus.

</para>

<simpara>

Die folgenden Algorithmen werden zur Zeit unterstützt:

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

<constant>PASSWORD_DEFAULT</constant> - Verwendet den bcrypt-Algorithmus

(Standard in PHP 5.5.0). Es ist zu beachten, dass sich diese Konstante

mit der Zeit ändern wird, wenn stärkere Algorithmen in PHP implementiert

werden. Aus diesem Grund kann sich die Länge des zurückgegebenen Strings

mit der Zeit ändern. Es wird deshalb empfohlen das Ergebnis in einem

Datenbankfeld zu speichern, das mehr als 60 Bytes speichern kann (255

Bytes wären eine gute Wahl).

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_BCRYPT</constant> - Verwendet den bcrypt-Algorithmus

zum Erstellen des Hashes. Dieser erstellt einen

<function>crypt</function>-kompatiblen Hash und benutzt die

<literal>$2y$</literal>-Kennung.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2I</constant> - Verwendet den

Argon2i-Algorithmus zur Erstellung des Hashes. Dieser Algorithmus ist

nur verfügbar, wenn PHP mit Argon2-Unterstützung kompiliert wurde.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2ID</constant> - Verwendet den

Argon2id-Algorithmus zur Erstellung des Hashes. Dieser Algorithmus ist

nur verfügbar, wenn PHP mit Argon2-Unterstützung kompiliert wurde.

</simpara>

</listitem>

</itemizedlist>

</para>

<simpara>

Unterstützte Optionen für <constant>PASSWORD_BCRYPT</constant>:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>salt</literal> (<type>string</type>) - um manuell ein Salt

anzugeben, das beim Hashing des Passworts verwendet wird. Es ist zu

beachten, dass diese Option die automatische Generierung des Salt

verhindert.

</para>

<para>

Wenn diese Option nicht angegeben wird, erzeugt die Funktion

<function>password_hash</function> für jedes gehashte Passwort ein

zufälliges Salt. Dies ist die vorgesehene Funktionsweise.

</para>

<warning>

<para>

Die salt-Option wird missbilligt. Es wird nun empfohlen, einfach das

Salt zu verwenden, das standardmäßig erzeugt wird. Ab PHP 8.0.0 wird

ein explizit angegebenes Salt ignoriert.

</para>

</warning>

</listitem>

<listitem>

<para>

<literal>cost</literal> (<type>int</type>) - bezeichnet die

algorithmischen Kosten, die verwendet werden sollen. Beispiele für

diesen Wert finden Sie finden Sie auf der Seite

<function>crypt</function>.

</para>

<para>

Wenn diese Option nicht angegeben wird, wird ein Standardwert von

<literal>12</literal> verwendet. Dies ist eine gute Basis für die

Kosten, sollte aber der verwendeten Hardware entsprechend angepasst

werden.

</para>

</listitem>

</itemizedlist>

</para>

<simpara>

Unterstützte Optionen für <constant>PASSWORD_ARGON2I</constant> und

<constant>PASSWORD_ARGON2ID</constant>:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>memory_cost</literal> (<type>int</type>) - Maximaler Speicher

(in Kibibytes), der zum Berechnen des Argon2-Hashes verwendet werden

darf. Der Standardwert ist

<constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>time_cost</literal> (<type>int</type>) - Maximale Zeit, die

die das Berechnen des Argon2-Hashes dauern darf. Der Standardwert ist

<constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>threads</literal> (<type>int</type>) - Anzahl der zu

verwendenden Threads zum Berechnen des Argon2-Hashes. Der Standardwert

ist <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.

</para>

<warning>

<para>

Nur verfügbar, wenn PHP libargon2 verwendet, nicht für

libsodium-Implementierungen.

</para>

</warning>

</listitem>

</itemizedlist>

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>password</parameter></term>

<listitem>

<para>

&password.parameter.password;

</para>

<caution>

<para>

Die Verwendung von <constant>PASSWORD_BCRYPT</constant> als

Algorithmus führt dazu, dass der Parameter

<parameter>password</parameter> auf eine Höchstlänge von 72 Bytes

gekürzt wird.

</para>

</caution>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>algo</parameter></term>

<listitem>

<para>

&password.parameter.algo;

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

&password.parameter.options;

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Gibt den Passwort-Hash zurück.

</para>

<para>

Der verwendete Algorithmus, der Aufwand und das Salt werden als Teil des

Hashes zurückgegeben. Daher sind alle Informationen, die benötigt werden,

um den Hash zu verifizieren, darin enthalten. Dies erlaubt es der Funktion

<function>password_verify</function> den Hash zu überprüfen, ohne dass eine

separate Speicherung für das Salt oder die Algorithmus-Informationen

erforderlich ist.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

Der Standardwert der Option <literal>cost</literal> des

<constant>PASSWORD_BCRYPT</constant>-Algorithmus wurde von

<literal>10</literal> auf <literal>12</literal> erhöht.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

<function>password_hash</function> setzt nun die zugrundeliegende

<exceptionname>Random\RandomException</exceptionname> als

<property>Exception::$previous</property>-Exception, wenn aufgrund

eines Fehlers bei der Erzeugung des Salt ein

<exceptionname>ValueError</exceptionname> ausgelöst wird.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<function>password_hash</function> gibt im Fehlerfall nicht mehr

&false; zurück; stattdessens wird ein

<classname>ValueError</classname> ausgelöst, wenn der

Passwort-Hashing-Algorithmus ungültig ist, oder ein

<classname>Error</classname>, wenn das Passwort-Hashing aufgrund eines

unbekannten Fehlers fehlschlug.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Der Parameter <parameter>algo</parameter> ist jetzt nullable

(akzeptiert den NULL-Wert).

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Der Parameter <parameter>algo</parameter> erwartet nun einen &string;,

akzeptiert aber aus Gründen der Abwärtskompatibilität noch immer

&integer;.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Die Sodium-Erweiterung bietet eine alternative Implementierung für

Argon2-Passwörter.

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

Mit <constant>PASSWORD_ARGON2ID</constant> wurde die Unterstützung

für Argon2id-Passwörter hinzugefügt.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Mit <constant>PASSWORD_ARGON2I</constant> wurde die Unterstützung für

Argon2i-Passwörter hinzugefügt.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>password_hash</function>-Beispiel</title>

<programlisting role="php">

<![CDATA[

<?php

echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

]]>

</screen>

</example>

</para>

<para>

<example>

<title><function>password_hash</function>-Beispiel mit manuell festgelegten Kosten</title>

<programlisting role="php">

<![CDATA[

<?php

$optionen = [

// Erhöhen der bcrypt-Kosten von 12 auf 13.

'cost' => 13,

];

echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $optionen);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

]]>

</screen>

</example>

</para>

<para>

<example>

<title><function>password_hash</function>-Beispiel für die Suche nach angemessenen Kosten</title>

<simpara>

Mit diesem Code wird ein Benchmarking des Rechners durchgeführt, um

festzustellen, wie hoch die Kosten sein dürfen, ohne die

Benutzerfreundlichkeit zu beeinträchtigen. Es wird empfohlen, die höchsten

Kosten festzulegen, die andere Operationen, die der Rechner ausführen

soll, nicht verlangsamen. 11 ist ein guter Richtwert, mehr ist besser,

wenn der Rechner schnell genug ist. Der nachstehende Code zielt auf eine

Ausführungszeit von ≤ 350 Millisekunden ab, was für Systeme, die

interaktive Anmeldungen verarbeiten, eine angemessene Verzögerung

darstellt.

</simpara>

<programlisting role="php">

<![CDATA[

<?php

$zeitZiel = 0.350; // 350 Millisekunden

$kosten = 11;

do {

$kosten++;

$start = microtime(true);

password_hash("test", PASSWORD_BCRYPT, ["cost" => $kosten]);

$ende = microtime(true);

} while (($ende - $start) < $zeitZiel);

echo "Ermittelte angemessene Kosten: " . $kosten - 1;

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Ermittelte angemessene Kosten: 13

]]>

</screen>

</example>

</para>

<para>

<example>

<title><function>password_hash</function>-Beispiel, das Argon2i verwendet</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Argon2i-Hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Argon2i-Hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

Es wird dringend empfohlen, kein explizites Salt für diese Funktion anzugeben.

Wenn kein Salt angegeben wird, wird automatisch ein sicheres Salt erstellt.

</para>

<para>

Wie oben erwähnt, erzeugt die Angabe der Option <literal>salt</literal> in

PHP 7.0.0 eine Missbilligungs-Warnung. Die Unterstützung für die manuelle

Angabe eines Salzes wurde in PHP 8.0.0 entfernt.

</para>

</caution>

<note>

<para>

Es wird empfohlen, diese Funktion auf dem verwendeten Rechner zu testen und

den Kostenparameter so einzustellen, dass die Ausführung der Funktion bei

interaktiven Anmeldungen weniger als 350 Millisekunden dauert.

Das Skript im obigen Beispiel hilft bei der Auswahl eines geeigneten

bcrypt-Kostenwerts für den jeweiligen Rechner.

</para>

</note>

<note>

<simpara>

Aktualisierungen der unterstützten Algorithmen durch diese Funktion (oder

Änderungen am Standardalgorithmus) müssen den folgenden Regeln folgen:

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

Jeder neue Algorithmus muss für mindestens 1 Vollversion im Core von

PHP sein, bevor er zum Standard wird. Wenn also &zb; ein neuer

Algorithmus in 7.5.5 hinzugefügt wird, wäre er erst in 7.7 als Standard

geeignet (da 7.6 die erste Vollversion wäre). Wenn aber ein anderer

Algorithmus in 7.6.0 hinzugefügt würde, wäre auch dieser für die

Standardeinstellung in 7.7.0 freigegeben.

</simpara>

</listitem>

<listitem>

<simpara>

Die Voreinstellung sollte sich nur bei einer Vollversion (7.3.0, 8.0.0,

etc) ändern und nicht bei einer Korrekturversion. Die einzige Ausnahme

hiervon ist in einem Notfall, wenn eine kritische Sicherheitslücke in

der aktuellen Voreinstellung gefunden wurde.

</simpara>

</listitem>

</itemizedlist>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>password_verify</function></member>

<member><function>password_needs_rehash</function></member>

<member><function>crypt</function></member>

<member><function>sodium_crypto_pwhash_str</function></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->