PHP 5.5 密碼雜湊 API 完整指南：建立、驗證與重新雜湊

前言

PHP 5.5 引入了專門的密碼雜湊 API，提供四個核心函數：password_hash()、password_verify()、password_needs_rehash() 和 password_get_info()。這組 API 採用 Bcrypt 為預設演算法，內建鹽值生成與成本因子調整，讓開發者能以最少的程式碼實現工業級的密碼儲存安全。

核心函數詳解

1. password_hash() — 建立安全雜湊

此函數自動處理鹽值生成與演算法選擇，語法如下：

string password_hash ( string $password , int $algo [, array $options ] )

• $password：使用者輸入的明文密碼
• $algo：演算法常數，推薦 PASSWORD_BCRYPT（預設）或 PASSWORD_ARGON2ID（PHP 7.3+）
• $options：選擇性陣列，可指定 cost（運算成本，預設 10）與 salt（不建議手動指定，PHP 7.0+ 已棄用）

基本範例

$password = 'user_password_123';
$hash = password_hash($password, PASSWORD_BCRYPT);
// 輸出範例：$2y$10$uOegXJ09qznQsKvPfxr61uWjpJBxVDH2KGJQVnodzjnglhs2WTwHu

自訂成本因子

$options = ['cost' => 12]; // 增加運算成本，提高暴力破解難度
$hash = password_hash($password, PASSWORD_BCRYPT, $options);

注意：cost 值建議在 10~12 之間，過高會導致登入延遲，過低則降低安全性。

2. password_verify() — 驗證密碼

無需手動提取鹽值或演算法，函數會從雜湊字串解析所需資訊：

bool password_verify ( string $password , string $hash )

使用範例

$hash = '$2y$10$JDJ5JDEwJDhsTHV6SGVIQuprRHZnGQsUEtlk8Iem0okH6HPyCoo22';

if (password_verify('user_password_123', $hash)) {
    echo '密碼正確，登入成功';
} else {
    echo '密碼錯誤';
}

3. password_get_info() — 取得雜湊資訊

回傳關聯陣列，包含演算法代碼、名稱與選項：

$info = password_get_info($hash);
print_r($info);
/* 輸出範例：
Array
(
    [algo] => 1
    [algoName] => bcrypt
    [options] => Array ( [cost] => 10 )
)
*/

4. password_needs_rehash() — 檢查是否需重新雜湊

當安全策略變更（如提高 cost、更換演算法）時，用於偵測舊雜湊是否符合新標準：

bool password_needs_rehash ( string $hash , int $algo [, array $options ] )

實務應用：登入時自動升級雜湊

if (password_verify($password, $storedHash)) {
    if (password_needs_rehash($storedHash, PASSWORD_BCRYPT, ['cost' => 12])) {
        $newHash = password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
        // 更新資料庫中的雜湊值
        $db->update('users', ['password_hash' => $newHash], ['id' => $userId]);
    }
    // 登入成功邏輯...
}

最佳實踐總結

1. 永遠使用 password_hash() 與 password_verify()，勿自行實作雜湊邏輯。
2. 資料庫欄位長度至少 255 字元，以容納未來演算法變更產生的更長雜湊。
3. 定期檢視 password_needs_rehash()，配合安全策略更新逐步升級舊雜湊。
4. PHP 7.3+ 建議改用 PASSWORD_ARGON2ID，提供更強的抗 GPU 破解能力。

常見錯誤與迷思

• ❌ 手動指定 salt 選項（PHP 7.0+ 已棄用，且手動鹽值通常比內建隨機鹽值弱）。
• ❌ 使用 md5()、sha1() 或 hash() 處理密碼（速度太快，極易被彩虹表與暴力破解）。
• ❌ 將雜湊儲存在長度不足的欄位（如 VARCHAR(60) 可能不夠）。