PHP 5.5+ 密碼雜湊 API 完整指南：password_hash、verify 與 rehash

引言

PHP 5.5.0 引入 Password Hashing API，提供安全、簡單的密碼雜湊與驗證機制，取代手動 md5()/sha1() + 鹽值的錯誤做法。核心四函式：

• password_hash() —— 建立雜湊
• password_verify() —— 驗證密碼
• password_get_info() —— 取得雜湊資訊
• password_needs_rehash() —— 檢查是否需重新雜湊

一、建立雜湊：password_hash()

$password = 'foo';
$hash = password_hash($password, PASSWORD_BCRYPT);
// 結果範例：$2y$10$uOegXJ09qznQsKvPfxr61uWjpJBxVDH2KGJQVnodzjnglhs2WTwHu

支援演算法常數：PASSWORD_BCRYPT（預設）、PASSWORD_ARGON2I、PASSWORD_ARGON2ID（PHP 7.2+）。

進階選項：cost 與 salt

$options = [
    'cost' => 12, // BCRYPT 成本因子，預設 10，愈大愈慢愈安全
    'salt' => random_bytes(16), // PHP 7.0+ 建議省略，讓函式自動產生
];
$hash = password_hash($password, PASSWORD_BCRYPT, $options);

注意： PHP 7.0 起 salt 選項已棄用，請讓 API 自行處理。

二、查看雜湊資訊：password_get_info()

var_dump(password_get_info($hash));
/*
array(3) {
  ["algo"]=> int(1)           // 演算法代碼
  ["algoName"]=> string(6) "bcrypt"
  ["options"]=> array(1) { ["cost"]=> int(12) }
}
*/

三、檢查是否需重新雜湊：password_needs_rehash()

當你想提高 cost 或更換演算法時，可在登入驗證成功後呼叫：

if (password_needs_rehash($hash, PASSWORD_BCRYPT, ['cost' => 12])) {
    $newHash = password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
    // 更新資料庫儲存的 $newHash
}

此函式不需驗證密碼，僅依演算法與選項判斷。

四、驗證密碼：password_verify()

$hash = '$2y$10$JDJ5JDEwJDhsTHV6SGVIQuprRHZnGQsUEtlk8Iem0okH6HPyCoo22';
var_dump(password_verify('foo', $hash)); // true
var_dump(password_verify('bar', $hash)); // false

回傳 bool，內部採用恆定時間比較，防止時序攻擊。

五、完整登入/註冊流程範例

// 註冊
function register($username, $password) {
    $hash = password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
    // INSERT INTO users (username, password_hash) VALUES (?, ?)
}

// 登入
function login($username, $password) {
    // SELECT password_hash FROM users WHERE username = ?
    $hash = $row['password_hash'];
    if (password_verify($password, $hash)) {
        if (password_needs_rehash($hash, PASSWORD_BCRYPT, ['cost' => 12])) {
            $newHash = password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
            // UPDATE users SET password_hash = ? WHERE username = ?
        }
        return true; // 登入成功
    }
    return false;
}

六、常見誤區與最佳實務

結語

Password Hashing API 是 PHP 官方推薦的密碼儲存標準，簡單、安全、可遷移。請在所有新專案中採用，並逐步遷移舊系統。

1. 上一篇文章： 33 道 PHP 經典面試題與詳解答案（含核心知識點）
2. 下一篇文章： PHP PDO 類完整教學：從連線、查詢到預處理與交易

PHP 綜合知識

深入理解 PHP 陣列與 foreach：HashTable 底層、引用行為、最佳實踐全解析

PHP 陣列本質：有序映射 PHP 陣列底層是 HashTa

PHP 檔案類型偵測：透過 Magic Bytes (檔案頭) 實作通用驗證類別

為什麼不能只信副檔名？ 攻擊者可上傳 shell.php.j

PHP 使用 Ming 庫動態生成 Flash 動畫：從入門到圖文混排完整指南

背景與動機 文章發表於 Web 2.0 早期，介紹如何使用

PHP Cookie完整指南：建立、讀取、刪除、生命週期、安全配置與實戰範例

Cookie 是 HTTP 無狀態特性下的關鍵狀態保持機制。