<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Creates a password hash</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.password-get-info.html">password_get_info</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.password-needs-rehash.html">password_needs_rehash</a></div>
<div class="up"><a href="ref.password.html">Password Hashing Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.password-hash" class="refentry">
<div class="refnamediv">
<h1 class="refname">password_hash</h1>
<p class="verinfo">(PHP 5 >= 5.5.0, PHP 7)</p><p class="refpurpose"><span class="refname">password_hash</span> — <span class="dc-title">Creates a password hash</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.password-hash-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">string</span> <span class="methodname"><strong>password_hash</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code></span>
, <span class="methodparam"><span class="type">int</span> <code class="parameter">$algo</code></span>
[, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code></span>
] )</div>
<p class="para rdfs-comment">
<span class="function"><strong>password_hash()</strong></span> creates a new password hash using a strong one-way hashing
algorithm. <span class="function"><strong>password_hash()</strong></span> is compatible with <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span>.
Therefore, password hashes created by <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> can be used with
<span class="function"><strong>password_hash()</strong></span>.
</p>
<p class="simpara">
The following algorithms are currently supported:
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
<strong><code>PASSWORD_DEFAULT</code></strong> - Use the bcrypt algorithm (default as of PHP 5.5.0).
Note that this constant is designed to change over time as new and stronger algorithms are added
to PHP. For that reason, the length of the result from using this identifier can change over
time. Therefore, it is recommended to store the result in a database column that can expand
beyond 60 characters (255 characters would be a good choice).
</span>
</li>
<li class="listitem">
<span class="simpara">
<strong><code>PASSWORD_BCRYPT</code></strong> - Use the <strong><code>CRYPT_BLOWFISH</code></strong> algorithm to
create the hash. This will produce a standard <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> compatible hash using
the "$2y$" identifier. The result will always be a 60 character string, or <strong><code>FALSE</code></strong> on failure.
</span>
</li>
<li class="listitem">
<span class="simpara">
<strong><code>PASSWORD_ARGON2I</code></strong> - Use the Argon2i hashing algorithm to create the hash.
This algorithm is only available if PHP has been compiled with Argon2i support.
</span>
</li>
</ul>
</p>
<p class="simpara">
Supported options for <strong><code>PASSWORD_BCRYPT</code></strong>:
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
<em>salt</em> (<span class="type"><a href="language.types.string.html" class="type string">string</a></span>) - to manually provide a salt to use when hashing the password.
Note that this will override and prevent a salt from being automatically generated.
</p>
<p class="para">
If omitted, a random salt will be generated by <span class="function"><strong>password_hash()</strong></span> for
each password hashed. This is the intended mode of operation.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
The salt option has been deprecated as of PHP 7.0.0. It is now
preferred to simply use the salt that is generated by default.
</p>
</div>
</li>
<li class="listitem">
<p class="para">
<em>cost</em> (<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span>) - which denotes the algorithmic cost that should be used.
Examples of these values can be found on the <span class="function"><a href="function.crypt.html" class="function">crypt()</a></span> page.
</p>
<p class="para">
If omitted, a default value of <em>10</em> will be used. This is a good
baseline cost, but you may want to consider increasing it depending on your hardware.
</p>
</li>
</ul>
</p>
<p class="simpara">
Supported options for <strong><code>PASSWORD_ARGON2I</code></strong>:
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
<em>memory_cost</em> (<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span>) - Maximum memory (in kibibytes) that may
be used to compute the Argon2 hash. Defaults to <strong><code>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</code></strong>.
</p>
</li>
<li class="listitem">
<p class="para">
<em>time_cost</em> (<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span>) - Maximum amount of time it may
take to compute the Argon2 hash. Defaults to <strong><code>PASSWORD_ARGON2_DEFAULT_TIME_COST</code></strong>.
</p>
</li>
<li class="listitem">
<p class="para">
<em>threads</em> (<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span>) - Number of threads to use for computing
the Argon2 hash. Defaults to <strong><code>PASSWORD_ARGON2_DEFAULT_THREADS</code></strong>.
</p>
</li>
</ul>
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.password-hash-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<code class="parameter">password</code></dt>
<dd>
<p class="para">
The user's password.
</p>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
Using the <strong><code>PASSWORD_BCRYPT</code></strong> as the
algorithm, will result
in the <code class="parameter">password</code> parameter being truncated to a
maximum length of 72 characters.
</p>
</div>
</dd>
<dt>
<code class="parameter">algo</code></dt>
<dd>
<p class="para">
A <a href="password.constants.html" class="link">password algorithm constant</a> denoting the algorithm to use when hashing the password.
</p>
</dd>
<dt>
<code class="parameter">options</code></dt>
<dd>
<p class="para">
An associative array containing options. See the <a href="password.constants.html" class="link">password algorithm constants</a> for documentation on the supported options for each algorithm.
</p>
<p class="para">
If omitted, a random salt will be created and the default cost will be
used.
</p>
</dd>
</dl>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.password-hash-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the hashed password, or <strong><code>FALSE</code></strong> on failure.
</p>
<p class="para">
The used algorithm, cost and salt are returned as part of the hash. Therefore,
all information that's needed to verify the hash is included in it. This allows
the <span class="function"><a href="function.password-verify.html" class="function">password_verify()</a></span> function to verify the hash without
needing separate storage for the salt or algorithm information.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.password-hash-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-991">
<p><strong>Example #1 <span class="function"><strong>password_hash()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * We just want to hash our password using the current DEFAULT algorithm.<br /> * This is presently BCRYPT, and will produce a 60 character result.<br /> *<br /> * Beware that DEFAULT may change over time, so you would want to prepare<br /> * By allowing your storage to expand past 60 characters (255 would be good)<br /> */<br /></span><span style="color: #007700">echo </span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"rasmuslerdorf"</span><span style="color: #007700">, </span><span style="color: #0000BB">PASSWORD_DEFAULT</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-992">
<p><strong>Example #2 <span class="function"><strong>password_hash()</strong></span> example setting cost manually</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * In this case, we want to increase the default cost for BCRYPT to 12.<br /> * Note that we also switched to BCRYPT, which will always be 60 characters.<br /> */<br /></span><span style="color: #0000BB">$options </span><span style="color: #007700">= [<br /> </span><span style="color: #DD0000">'cost' </span><span style="color: #007700">=> </span><span style="color: #0000BB">12</span><span style="color: #007700">,<br />];<br />echo </span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"rasmuslerdorf"</span><span style="color: #007700">, </span><span style="color: #0000BB">PASSWORD_BCRYPT</span><span style="color: #007700">, </span><span style="color: #0000BB">$options</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-993">
<p><strong>Example #3 <span class="function"><strong>password_hash()</strong></span> example finding a good cost</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * This code will benchmark your server to determine how high of a cost you can<br /> * afford. You want to set the highest cost that you can without slowing down<br /> * you server too much. 8-10 is a good baseline, and more is good if your servers<br /> * are fast enough. The code below aims for ≤ 50 milliseconds stretching time,<br /> * which is a good baseline for systems handling interactive logins.<br /> */<br /></span><span style="color: #0000BB">$timeTarget </span><span style="color: #007700">= </span><span style="color: #0000BB">0.05</span><span style="color: #007700">; </span><span style="color: #FF8000">// 50 milliseconds <br /><br /></span><span style="color: #0000BB">$cost </span><span style="color: #007700">= </span><span style="color: #0000BB">8</span><span style="color: #007700">;<br />do {<br /> </span><span style="color: #0000BB">$cost</span><span style="color: #007700">++;<br /> </span><span style="color: #0000BB">$start </span><span style="color: #007700">= </span><span style="color: #0000BB">microtime</span><span style="color: #007700">(</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">"test"</span><span style="color: #007700">, </span><span style="color: #0000BB">PASSWORD_BCRYPT</span><span style="color: #007700">, [</span><span style="color: #DD0000">"cost" </span><span style="color: #007700">=> </span><span style="color: #0000BB">$cost</span><span style="color: #007700">]);<br /> </span><span style="color: #0000BB">$end </span><span style="color: #007700">= </span><span style="color: #0000BB">microtime</span><span style="color: #007700">(</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br />} while ((</span><span style="color: #0000BB">$end </span><span style="color: #007700">- </span><span style="color: #0000BB">$start</span><span style="color: #007700">) < </span><span style="color: #0000BB">$timeTarget</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"Appropriate Cost Found: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$cost</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Appropriate Cost Found: 10
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-994">
<p><strong>Example #4 <span class="function"><strong>password_hash()</strong></span> example using Argon2</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">'Argon2 hash: ' </span><span style="color: #007700">. </span><span style="color: #0000BB">password_hash</span><span style="color: #007700">(</span><span style="color: #DD0000">'rasmuslerdorf'</span><span style="color: #007700">, </span><span style="color: #0000BB">PASSWORD_ARGON2I</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Argon2 hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.password-hash-notes">
<h3 class="title">Notes</h3>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
It is strongly recommended that you do not generate your own salt for this
function. It will create a secure salt automatically for you if you do
not specify one.
</p>
<p class="para">
As noted above, providing the <em>salt</em> option in PHP 7.0
will generate a deprecation warning. Support for providing a salt manually
may be removed in a future PHP release.
</p>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
It is recommended that you test this function on your servers, and adjust the cost parameter
so that execution of the function takes less than 100 milliseconds on interactive systems.
The script in the above example will help you choose a good cost value for your hardware.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
Updates to supported algorithms by this function (or changes to the default one) must follow
the following rules:
</span>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Any new algorithm must be in core for at least 1 full release of PHP
prior to becoming default. So if, for example, a new algorithm is added
in 7.5.5, it would not be eligible for default until 7.7 (since 7.6
would be the first full release). But if a different algorithm was added
in 7.6.0, it would also be eligible for default at 7.7.0.
</span>
</li>
<li class="listitem">
<span class="simpara">
The default should only change in a full release (7.3.0, 8.0.0, etc)
and not in a revision release. The only exception to this is in an
emergency when a critical security flaw is found in the current
default.
</span>
</li>
</ul>
</p>
</p></blockquote>
</div>
<div class="refsect1 changelog" id="refsect1-function.password-hash-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>7.2.0</td>
<td>
Support for Argon2 passwords using <strong><code>PASSWORD_ARGON2I</code></strong> was added.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.password-hash-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><span class="function"><a href="function.password-verify.html" class="function" rel="rdfs-seeAlso">password_verify()</a> - Verifies that a password matches a hash</span></li>
<li class="member"><span class="function"><a href="function.crypt.html" class="function" rel="rdfs-seeAlso">crypt()</a> - One-way string hashing</span></li>
<li class="member"><a href="https://github.com/ircmaxell/password_compat" class="link external">» userland implementation</a></li>
<li class="member"><span class="function"><a href="function.sodium-crypto-pwhash-str.html" class="function" rel="rdfs-seeAlso">sodium_crypto_pwhash_str()</a> - Get an ASCII encoded hash</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.password-get-info.html">password_get_info</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.password-needs-rehash.html">password_needs_rehash</a></div>
<div class="up"><a href="ref.password.html">Password Hashing Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
