密码加密算法更换时，如何借助 password_needs_rehash 实现平滑过渡？

gitbox 2025-09-18

在现代 Web 开发中，确保用户密码的安全性是至关重要的。随着技术的进步，新的加密算法不断涌现，旧的算法可能会随着时间的推移变得不再安全或不再适合当前的需求。因此，开发人员通常需要在不影响用户体验的情况下更换密码加密算法。PHP 提供了 password_needs_rehash() 函数，这使得密码加密算法的平滑过渡变得更加简单和高效。

1. 什么是 password_needs_rehash()？

password_needs_rehash() 是 PHP 内置的一个函数，用于检查存储的密码是否需要重新加密。它的作用是判断当前存储的密码哈希值是否与新的密码加密算法匹配，或者是否满足新的算法要求。通常情况下，当密码加密算法发生变化时，开发者可以利用该函数在用户登录时自动更新密码哈希，而不需要用户手动重置密码。

该函数的定义如下：

<span><span><span class="hljs-keyword">bool</span></span><span> </span><span><span class="hljs-title function_ invoke__">password_needs_rehash</span></span><span> ( </span><span><span class="hljs-keyword">string</span></span><span> </span><span><span class="hljs-variable">$hash</span></span><span> , </span><span><span class="hljs-keyword">int</span></span><span> </span><span><span class="hljs-variable">$algo</span></span><span> , </span><span><span class="hljs-keyword">array</span></span><span> </span><span><span class="hljs-variable">$options</span></span><span> )
</span></span>

参数解释：

$hash：存储的密码哈希值。
$algo：新的加密算法（例如 PASSWORD_BCRYPT、PASSWORD_ARGON2I 等）。
$options：可选的配置选项，通常是一个包含算法配置的数组，如 bcrypt 的成本因子。

返回值：

返回 true 如果密码需要重新哈希，返回 false 如果不需要重新哈希。

2. 如何在密码加密算法更换时使用 password_needs_rehash()？

步骤 1：用户登录时验证密码

当用户登录时，我们首先使用旧的加密算法验证用户输入的密码。此时，我们还需要检查存储的密码哈希是否需要重新加密。如果需要，则使用新的算法对密码进行加密，并更新数据库中的哈希值。

步骤 2：检查密码是否需要重新加密

在验证用户密码成功后，可以通过 password_needs_rehash() 函数判断当前存储的密码哈希是否符合新的加密算法要求。如果哈希值需要重新加密，使用新的算法进行加密并更新哈希。

代码示例：

假设我们原来使用的是 PASSWORD_BCRYPT 加密算法，现在需要升级到 PASSWORD_ARGON2I。

<span><span><span class="hljs-comment">// 获取用户输入的密码</span></span><span>
</span><span><span class="hljs-variable">$user_input_password</span></span><span> = </span><span><span class="hljs-variable">$_POST</span></span><span>[</span><span><span class="hljs-string">'password'</span></span><span>];

</span><span><span class="hljs-comment">// 从数据库中获取存储的哈希值</span></span><span>
</span><span><span class="hljs-variable">$stored_hash</span></span><span> = </span><span><span class="hljs-title function_ invoke__">getUserHashFromDatabase</span></span><span>(</span><span><span class="hljs-variable">$user_id</span></span><span>);

</span><span><span class="hljs-comment">// 使用旧的加密算法验证密码</span></span><span>
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">password_verify</span></span><span>(</span><span><span class="hljs-variable">$user_input_password</span></span><span>, </span><span><span class="hljs-variable">$stored_hash</span></span><span>)) {
    
    </span><span><span class="hljs-comment">// 如果哈希值需要重新加密</span></span><span>
    </span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">password_needs_rehash</span></span><span>(</span><span><span class="hljs-variable">$stored_hash</span></span><span>, PASSWORD_ARGON2I, [</span><span><span class="hljs-string">'memory_cost'</span></span><span> =&gt; </span><span><span class="hljs-number">1</span></span><span> &lt;&lt; </span><span><span class="hljs-number">17</span></span><span>, </span><span><span class="hljs-string">'time_cost'</span></span><span> =&gt; </span><span><span class="hljs-number">4</span></span><span>, </span><span><span class="hljs-string">'threads'</span></span><span> =&gt; </span><span><span class="hljs-number">2</span></span><span>])) {
        
        </span><span><span class="hljs-comment">// 使用新的加密算法对密码进行加密</span></span><span>
        </span><span><span class="hljs-variable">$new_hash</span></span><span> = </span><span><span class="hljs-title function_ invoke__">password_hash</span></span><span>(</span><span><span class="hljs-variable">$user_input_password</span></span><span>, PASSWORD_ARGON2I, [</span><span><span class="hljs-string">'memory_cost'</span></span><span> =&gt; </span><span><span class="hljs-number">1</span></span><span> &lt;&lt; </span><span><span class="hljs-number">17</span></span><span>, </span><span><span class="hljs-string">'time_cost'</span></span><span> =&gt; </span><span><span class="hljs-number">4</span></span><span>, </span><span><span class="hljs-string">'threads'</span></span><span> =&gt; </span><span><span class="hljs-number">2</span></span><span>]);
        
        </span><span><span class="hljs-comment">// 更新数据库中的哈希值</span></span><span>
        </span><span><span class="hljs-title function_ invoke__">updateUserHashInDatabase</span></span><span>(</span><span><span class="hljs-variable">$user_id</span></span><span>, </span><span><span class="hljs-variable">$new_hash</span></span><span>);
    }

    </span><span><span class="hljs-comment">// 登录成功，执行相应的操作</span></span><span>
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"登录成功！"</span></span><span>;
} </span><span><span class="hljs-keyword">else</span></span><span> {
    </span><span><span class="hljs-comment">// 密码错误</span></span><span>
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"密码错误！"</span></span><span>;
}
</span></span>

代码解释：

password_verify()：用于验证用户输入的密码是否与存储的哈希值匹配。
password_needs_rehash()：在验证成功后，检查存储的哈希是否符合新的加密算法要求。如果需要重新加密，则执行后续步骤。
password_hash()：用于使用新的加密算法对密码进行加密。
updateUserHashInDatabase()：将新的密码哈希存储到数据库中。

3. 平滑过渡的好处

使用 password_needs_rehash() 进行密码加密算法更换时，最大的好处是用户无需主动干预，系统可以在用户登录时自动完成密码哈希的升级。这种方式带来了几个重要的优势：

无缝升级：用户只需要登录一次，系统就会自动升级密码加密算法，无需重新设置密码。
提高安全性：通过逐步过渡到更安全的加密算法，系统可以提高整体的安全性，避免因使用过时的算法而导致的安全漏洞。
兼容性强：在更换加密算法的过程中，旧的哈希值依然有效，确保了系统的向后兼容性，不会影响已经注册的用户。

4. 总结

更换密码加密算法是增强安全性的必要措施之一，但在实施时需要考虑用户体验以及系统的平滑过渡。PHP 提供的 password_needs_rehash() 函数能够帮助开发人员在不干扰用户的情况下，平稳地将密码加密算法从旧的算法迁移到新的算法。通过这种方式，可以提高系统的安全性，同时确保用户的登录体验不会受到影响。