<!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)</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">integer</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>
<p class="para">
Supported Options:
</p>
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
<em>salt</em> - 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>
</li>
<li class="listitem">
<p class="para">
<em>cost</em> - 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>
</li>
</ul>
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.password-hash-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<span class="term"><em><code class="parameter">password</code></em></span>
<dd>
<p class="para">
The user's password.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">algo</code></em></span>
<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>
<dt>
<span class="term"><em><code class="parameter">options</code></em></span>
<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>
</dt>
</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>
</div>
<div class="refsect1 examples" id="refsect1-function.password-hash-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-872">
<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">).</span><span style="color: #DD0000">"\n"</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:</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-873">
<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">).</span><span style="color: #DD0000">"\n"</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:</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-874">
<p><strong>Example #3 <span class="function"><strong>password_hash()</strong></span> example setting salt 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 /> * Note that the salt here is randomly generated.<br /> * Never use a static salt or one that is not randomly generated.<br /> *<br /> * For the VAST majority of use-cases, let password_hash generate the salt randomly for you<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">11</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">'salt' </span><span style="color: #007700">=> </span><span style="color: #0000BB">mcrypt_create_iv</span><span style="color: #007700">(</span><span style="color: #0000BB">22</span><span style="color: #007700">, </span><span style="color: #0000BB">MCRYPT_DEV_URANDOM</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">).</span><span style="color: #DD0000">"\n"</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:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
$2y$11$q5MkhSBtlsJcNEVsYh64a.aCluzHnGog7TQAKVmQwO9C8xb.t89F.
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-875">
<p><strong>Example #4 <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. 10 is a good baseline, and more is good if your servers<br /> * are fast enough.<br /> */<br /></span><span style="color: #0000BB">$timeTarget </span><span style="color: #007700">= </span><span style="color: #0000BB">0.2</span><span style="color: #007700">; <br /><br /></span><span style="color: #0000BB">$cost </span><span style="color: #007700">= </span><span style="color: #0000BB">9</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">. </span><span style="color: #DD0000">"\n"</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:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Appropriate Cost Found: 11
</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>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
It is recommended that you should test this function on your servers, and adjust the cost
parameter so that execution of the function takes approximately 0.1 to 0.5 seconds. 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 follwoing 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 5.5.5, it would not be eligible for
default until 5.7 (since 5.6 would be the first full release). But if a different algorithm was
added in 5.6.0, it would also be eligible for default at 5.7.0.
</span>
</li>
<li class="listitem">
<span class="simpara">
The default should only change on a full release (5.6.0, 6.0.0, etc) and not on 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 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>
</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>
