為什麼password_needs_rehash 判斷密碼是否需要更新不准確？常見配置問題分析與解決

gitbox 2025-08-05

1. password_needs_rehash工作原理

password_needs_rehash函數會根據給定的密碼哈希、所選的算法、成本和其他選項，判斷當前存儲的密碼哈希是否需要更新。其函數簽名如下：

 <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_DEFAULT或PASSWORD_BCRYPT ）。
$options : 一組配置選項，通常包括哈希的成本。

這個函數的作用是檢查當前密碼的哈希是否符合當前配置要求。如果不符合，它會返回true ，表示需要更新哈希。

2. 常見配置問題

(1) PASSWORD_DEFAULT可能會發生變化

PASSWORD_DEFAULT是PHP 中的默認哈希算法，它通常使用bcrypt ，但未來可能會隨著算法的改進而更換。如果PHP 版本升級或安全庫發生變化， PASSWORD_DEFAULT可能會使用新的算法。

例如，假設在PHP 5.6 中，你使用PASSWORD_DEFAULT來生成密碼哈希並存儲。當PHP 升級到7.x 時， PASSWORD_DEFAULT可能會變成一個不同的算法（假設從bcrypt變成了argon2 ）。如果你使用password_needs_rehash來檢查密碼哈希時，可能會出現以下情況：

存儲的密碼使用了舊的哈希算法。
系統要求新的哈希算法（比如argon2 ），但password_needs_rehash無法檢測到這些差異。

解決方案

為了避免這種情況，最好明確指定一個算法而不是依賴PASSWORD_DEFAULT ，尤其是在生產環境中。即使PHP 將來切換到新的算法，也能保證你使用的是明確的、適合項目需求的哈希算法。

 <span><span><span class="hljs-variable">$hash</span></span><span> = </span><span><span class="hljs-title function_ invoke__">password_hash</span></span><span>(</span><span><span class="hljs-variable">$password</span></span><span>, PASSWORD_BCRYPT);
</span></span>

(2) 成本因子的變化

password_needs_rehash還會檢查密碼哈希的成本因子（例如，bcrypt 的成本因子）。如果你在系統配置中改變了成本因子（例如，從10 改為12），而舊的密碼哈希仍然使用較低的成本因子，那麼password_needs_rehash可能無法正確檢測到哈希需要更新。

解決方案

始終確保每次生成密碼哈希時都使用當前的成本因子。為了避免密碼哈希的更新滯後，可以在用戶每次登錄時檢查並更新密碼哈希。

 <span><span><span class="hljs-variable">$options</span></span><span> = [</span><span><span class="hljs-string">'cost'</span></span><span> =&gt; </span><span><span class="hljs-number">12</span></span><span>];  </span><span><span class="hljs-comment">// 使用合適的成本因子</span></span><span>
</span><span><span class="hljs-variable">$hash</span></span><span> = </span><span><span class="hljs-title function_ invoke__">password_hash</span></span><span>(</span><span><span class="hljs-variable">$password</span></span><span>, PASSWORD_BCRYPT, </span><span><span class="hljs-variable">$options</span></span><span>);
</span></span>

(3) password_needs_rehash的調用方式不當

password_needs_rehash需要三個參數：哈希值、算法以及配置選項。如果這些參數傳遞錯誤，可能導致函數無法正常工作。常見的問題包括：

未正確傳遞$options數組，導致成本因子或其他配置參數丟失。
傳遞的哈希值與生成該哈希時使用的算法不匹配。

解決方案

確保你在調用password_needs_rehash時傳遞正確的參數。以下是一個例子：

 <span><span><span class="hljs-variable">$hash</span></span><span> = </span><span><span class="hljs-title function_ invoke__">password_hash</span></span><span>(</span><span><span class="hljs-variable">$password</span></span><span>, PASSWORD_BCRYPT, [</span><span><span class="hljs-string">'cost'</span></span><span> =&gt; </span><span><span class="hljs-number">12</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">$hash</span></span><span>, PASSWORD_BCRYPT, [</span><span><span class="hljs-string">'cost'</span></span><span> =&gt; </span><span><span class="hljs-number">12</span></span><span>])) {
    </span><span><span class="hljs-variable">$hash</span></span><span> = </span><span><span class="hljs-title function_ invoke__">password_hash</span></span><span>(</span><span><span class="hljs-variable">$password</span></span><span>, PASSWORD_BCRYPT, [</span><span><span class="hljs-string">'cost'</span></span><span> =&gt; </span><span><span class="hljs-number">12</span></span><span>]);
}
</span></span>

確保$hash與所選擇的算法和配置選項一致。

3. 其他注意事項

(1) 需要定期更新密碼哈希

密碼哈希算法和配置可能隨著時間的推移變得更強大，但也可能在某個時點過時。因此，除了使用password_needs_rehash來判斷是否需要更新密碼哈希外，定期對密碼哈希進行重設也是一種良好的安全實踐。可以通過要求用戶定期更新密碼，或者在用戶每次登錄時檢查是否需要更新哈希。

(2) 兼容性問題

有時，你可能需要兼容多種不同的PHP 版本或配置。在這種情況下， password_needs_rehash的行為可能會受到不同版本之間的差異影響。因此，確保你的系統與所使用的PHP 版本兼容，並根據需要進行相應的調整。

4. 總結

password_needs_rehash是一個強大的工具，用於檢測密碼哈希是否符合當前的配置要求。然而，在實際使用過程中，我們可能會遇到一些配置問題，導致該函數判斷不准確。常見的配置問題包括算法的變化、成本因子的更新以及參數傳遞不當等。解決這些問題的方法是明確指定哈希算法和成本因子，確保每次更新密碼時都使用當前的配置，並定期審查密碼安全策略。

通過理解這些常見問題及其解決方案，我們能夠更好地保障用戶的密碼安全，避免潛在的安全隱患。

password_needs_rehash