mirror of
https://github.com/fofolee/uTools-Manuals.git
synced 2025-06-19 22:32:44 +08:00
358 lines
20 KiB
HTML
358 lines
20 KiB
HTML
<!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>创建密码的散列（hash）</title>
|
||
</head>
|
||
<body class="docs"><div id="layout">
|
||
<div id="layout-content"><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">创建密码的散列（hash）</span></p>
|
||
|
||
</div>
|
||
|
||
<div class="refsect1 description" id="refsect1-function.password-hash-description">
|
||
<h3 class="title">说明</h3>
|
||
<div class="methodsynopsis dc-description">
|
||
<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>
|
||
] ) : <span class="type">string</span></div>
|
||
|
||
<p class="para rdfs-comment">
|
||
<span class="function"><strong>password_hash()</strong></span> 使用足够强度的单向散列算法创建密码的散列（hash）。
|
||
|
||
<span class="function"><strong>password_hash()</strong></span> 兼容 <span class="function"><a href="crypt.html" class="function">crypt()</a></span>。
|
||
所以， <span class="function"><a href="crypt.html" class="function">crypt()</a></span> 创建的密码散列也可用于
|
||
<span class="function"><strong>password_hash()</strong></span>。
|
||
</p>
|
||
<p class="simpara">
|
||
当前支持的算法：
|
||
</p>
|
||
<p class="para">
|
||
<ul class="itemizedlist">
|
||
<li class="listitem">
|
||
<span class="simpara">
|
||
<strong><code>PASSWORD_DEFAULT</code></strong> - 使用 bcrypt 算法 (PHP 5.5.0 默认)。
|
||
注意，该常量会随着 PHP 加入更新更高强度的算法而改变。
|
||
所以，使用此常量生成结果的长度将在未来有变化。
|
||
因此，数据库里储存结果的列可超过60个字符（最好是255个字符）。
|
||
</span>
|
||
</li>
|
||
<li class="listitem">
|
||
<span class="simpara">
|
||
<strong><code>PASSWORD_BCRYPT</code></strong> - 使用 <strong><code>CRYPT_BLOWFISH</code></strong> 算法创建散列。
|
||
这会产生兼容使用 "$2y$" 的 <span class="function"><a href="crypt.html" class="function">crypt()</a></span>。
|
||
结果将会是 60 个字符的字符串， 或者在失败时返回 <strong><code>FALSE</code></strong>。
|
||
</span>
|
||
</li>
|
||
<li class="listitem">
|
||
<span class="simpara">
|
||
<strong><code>PASSWORD_ARGON2I</code></strong> - 使用 Argon2 散列算法创建散列。
|
||
</span>
|
||
</li>
|
||
</ul>
|
||
</p>
|
||
<p class="simpara">
|
||
<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>) - 手动提供散列密码的盐值（salt）。这将避免自动生成盐值（salt）。
|
||
</p>
|
||
<p class="para">
|
||
省略此值后，<span class="function"><strong>password_hash()</strong></span> 会为每个密码散列自动生成随机的盐值。这种操作是有意的模式。
|
||
</p>
|
||
<div class="warning"><strong class="warning">Warning</strong>
|
||
<p class="para">
|
||
盐值（salt）选项从 PHP 7.0.0 开始被废弃（deprecated）了。
|
||
现在最好选择简单的使用默认产生的盐值。
|
||
</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>) _ 代表算法使用的 cost。<span class="function"><a href="crypt.html" class="function">crypt()</a></span> 页面上有 cost 值的例子。
|
||
</p>
|
||
<p class="para">
|
||
省略时，默认值是 <em>10</em>。
|
||
这个 cost 是个不错的底线，但也许可以根据自己硬件的情况，加大这个值。
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</p>
|
||
<p class="simpara">
|
||
<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>) - 计算 Argon2 散列时的最大内存（单位：字节 byte）。默认值： <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>) - 计算 Argon2 散列时最多的时间。默认值： <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>) - 计算 Argon2 散列时最多的线程数。默认值： <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">参数</h3>
|
||
<dl>
|
||
|
||
|
||
<dt>
|
||
<code class="parameter">password</code></dt>
|
||
|
||
<dd>
|
||
|
||
<p class="para">
|
||
用户的密码。
|
||
</p>
|
||
<div class="caution"><strong class="caution">Caution</strong>
|
||
<p class="para">
|
||
使用<strong><code>PASSWORD_BCRYPT</code></strong> 做算法，将使 <code class="parameter">password</code> 参数最长为72个字符，超过会被截断。
|
||
</p>
|
||
</div>
|
||
</dd>
|
||
|
||
|
||
|
||
<dt>
|
||
<code class="parameter">algo</code></dt>
|
||
|
||
<dd>
|
||
|
||
<p class="para">
|
||
一个用来在散列密码时指示算法的<a href="password.constants.html" class="link">密码算法常量</a>。
|
||
</p>
|
||
</dd>
|
||
|
||
|
||
|
||
<dt>
|
||
<code class="parameter">options</code></dt>
|
||
|
||
<dd>
|
||
|
||
<p class="para">
|
||
一个包含有选项的关联数组。目前支持两个选项：<em>salt</em>，在散列密码时加的盐（干扰字符串），以及<em>cost</em>，用来指明算法递归的层数。这两个值的例子可在 <span class="function"><a href="crypt.html" class="function">crypt()</a></span> 页面找到。
|
||
</p>
|
||
<p class="para">
|
||
省略后，将使用随机盐值与默认 cost。
|
||
</p>
|
||
</dd>
|
||
|
||
|
||
</dl>
|
||
|
||
</div>
|
||
|
||
|
||
<div class="refsect1 returnvalues" id="refsect1-function.password-hash-returnvalues">
|
||
<h3 class="title">返回值</h3>
|
||
<p class="para">
|
||
返回散列后的密码， 或者在失败时返回 <strong><code>FALSE</code></strong>。
|
||
</p>
|
||
<p class="para">
|
||
使用的算法、cost 和盐值作为散列的一部分返回。所以验证散列值的所有信息都已经包含在内。
|
||
这使 <span class="function"><a href="password_verify.html" class="function">password_verify()</a></span> 函数验证的时候，不需要额外储存盐值或者算法的信息。
|
||
</p>
|
||
</div>
|
||
|
||
|
||
<div class="refsect1 examples" id="refsect1-function.password-hash-examples">
|
||
<h3 class="title">范例</h3>
|
||
<p class="para">
|
||
<div class="example" id="example-956">
|
||
<p><strong>Example #1 <span class="function"><strong>password_hash()</strong></span> 例子</strong></p>
|
||
<div class="example-contents">
|
||
<div class="phpcode"><pre><span style="color: #000000">
|
||
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * 我们想要使用默认算法散列密码<br /> * 当前是 BCRYPT，并会产生 60 个字符的结果。<br /> *<br /> * 请注意，随时间推移，默认算法可能会有变化，<br /> * 所以需要储存的空间能够超过 60 字（255字不错）<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>
|
||
</pre></div>
|
||
</div>
|
||
|
||
<div class="example-contents"><p>以上例程的输出类似于：</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-957">
|
||
<p><strong>Example #2 <span class="function"><strong>password_hash()</strong></span> 手动设置 cost 的例子</strong></p>
|
||
<div class="example-contents">
|
||
<div class="phpcode"><pre><span style="color: #000000">
|
||
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * 在这个案例里，我们为 BCRYPT 增加 cost 到 12。<br /> * 注意，我们已经切换到了，将始终产生 60 个字符。<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>
|
||
</pre></div>
|
||
</div>
|
||
|
||
<div class="example-contents"><p>以上例程的输出类似于：</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-958">
|
||
<p><strong>Example #3 <span class="function"><strong>password_hash()</strong></span> 手动设置盐值的例子</strong></p>
|
||
<div class="example-contents">
|
||
<div class="phpcode"><pre><span style="color: #000000">
|
||
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * 注意，这里的盐值是随机产生的。<br /> * 永远都不要使用固定盐值，或者不是随机生成的盐值。<br /> *<br /> * 绝大多数情况下，可以让 password_hash generate 为你自动产生随机盐值<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">);<br /></span><span style="color: #0000BB">?></span>
|
||
</span>
|
||
</pre></div>
|
||
</div>
|
||
|
||
<div class="example-contents"><p>以上例程的输出类似于：</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-959">
|
||
<p><strong>Example #4 寻找最佳 cost 的 <span class="function"><strong>password_hash()</strong></span> 例子</strong></p>
|
||
<div class="example-contents">
|
||
<div class="phpcode"><pre><span style="color: #000000">
|
||
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/**<br /> * 这个例子对服务器做了基准测试（benchmark），检测服务器能承受多高的 cost<br /> * 在不明显拖慢服务器的情况下可以设置最高的值<br /> * 8-10 是个不错的底线，在服务器够快的情况下，越高越好。<br /> * 以下代码目标为 ≤ 50 毫秒（milliseconds），<br /> * 适合系统处理交互登录。<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>
|
||
</pre></div>
|
||
</div>
|
||
|
||
<div class="example-contents"><p>以上例程的输出类似于：</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="openssl_spki_export_challenge.example.basic">
|
||
<p><strong>Example #5 使用 Argon2 的<span class="function"><strong>password_hash()</strong></span>例子</strong></p>
|
||
<div class="example-contents">
|
||
<div class="phpcode"><pre><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>
|
||
</pre></div>
|
||
</div>
|
||
|
||
<div class="example-contents"><p>以上例程的输出类似于：</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">注释</h3>
|
||
<div class="caution"><strong class="caution">Caution</strong>
|
||
<p class="para">
|
||
强烈建议不要自己为这个函数生成盐值（salt）。只要不设置，它会自动创建安全的盐值。
|
||
</p>
|
||
<p class="para">
|
||
就像以上提及的，在 PHP 7.0 提供 <em>salt</em>选项会导致废弃（deprecation）警告。
|
||
未来的 PHP 发行版里，手动提供盐值的功能可能会被删掉。
|
||
</p>
|
||
</div>
|
||
<blockquote class="note"><p><strong class="note">Note</strong>:
|
||
<p class="para">
|
||
在交互的系统上，推荐在自己的服务器上测试此函数，调整 cost 参数直至函数时间开销小于 100 毫秒（milliseconds）。
|
||
上面脚本的例子会帮助选择合适硬件的最佳 cost。
|
||
</p>
|
||
</p></blockquote>
|
||
<blockquote class="note"><p><strong class="note">Note</strong>:
|
||
<span class="simpara">
|
||
这个函数更新支持的算法时（或修改默认算法），必定会遵守以下规则：
|
||
</span>
|
||
<p class="para">
|
||
<ul class="itemizedlist">
|
||
<li class="listitem">
|
||
<span class="simpara">
|
||
任何内核中的新算法必须在经历一次 PHP 完整发行才能成为默认算法。
|
||
比如，在 PHP 7.5.5 中添加的新算法，在 PHP 7.7 之前不能成为默认算法
|
||
（由于 7.6 是第一个完整发行版）。
|
||
但如果是在 7.6.0 里添加的不同算法，在 7.7.0 里也可以成为默认算法。
|
||
</span>
|
||
</li>
|
||
<li class="listitem">
|
||
<span class="simpara">
|
||
仅仅允许在完整发行版中修改默认算法（比如 7.3.0, 8.0.0，等等），不能是在修订版。
|
||
唯一的例外是：在当前默认算法里发现了紧急的安全威胁。
|
||
</span>
|
||
</li>
|
||
</ul>
|
||
</p>
|
||
</p></blockquote>
|
||
</div>
|
||
|
||
|
||
<div class="refsect1 changelog" id="refsect1-function.password-hash-changelog">
|
||
<h3 class="title">更新日志</h3>
|
||
<p class="para">
|
||
<table class="doctable informaltable">
|
||
|
||
<thead>
|
||
<tr>
|
||
<th>版本</th>
|
||
<th>说明</th>
|
||
</tr>
|
||
|
||
</thead>
|
||
|
||
<tbody class="tbody">
|
||
<tr>
|
||
<td>7.2.0</td>
|
||
<td>
|
||
添加 <strong><code>PASSWORD_ARGON2I</code></strong>，支持 Argon2 密码散列算法。
|
||
</td>
|
||
</tr>
|
||
|
||
</tbody>
|
||
|
||
</table>
|
||
|
||
</p>
|
||
</div>
|
||
|
||
|
||
<div class="refsect1 seealso" id="refsect1-function.password-hash-seealso">
|
||
<h3 class="title">参见</h3>
|
||
<p class="para">
|
||
<ul class="simplelist">
|
||
<li class="member"><span class="function"><a href="password_verify.html" class="function" rel="rdfs-seeAlso">password_verify()</a> - 验证密码是否和散列值匹配</span></li>
|
||
<li class="member"><span class="function"><a href="crypt.html" class="function" rel="rdfs-seeAlso">crypt()</a> - 单向字符串散列</span></li>
|
||
<li class="member"><a href="https://github.com/ircmaxell/password_compat" class="link external">» 用户的使用</a></li>
|
||
</ul>
|
||
</p>
|
||
</div>
|
||
|
||
|
||
</div></div></div></body></html> |