安全指南

使用 Web Crypto 與拒絕採樣的客戶端密碼生成

一份技術白皮書，說明 PwdGen 的瀏覽器端密碼生成模型、熵界線、拒絕採樣與隱私限制。

摘要

PwdGen 使用客戶端參考生成方法：瀏覽器或執行環境的 Web Crypto 提供隨機位元組，拒絕採樣將這些位元組映射為無偏差的有限索引，然後透過 Fisher-Yates 洗牌將所需的字元類別分佈到最終密碼中。此方法刻意保持簡潔、可審計，並可在網頁應用程式、API 適配器、命令列工具以及預先準備的 pwdgen-core 套件中重現。

本文件說明工程模型。並非聲稱新的加密原語、正式標準或獨立第三方審計。

隨機性來源

生成器透過 crypto.getRandomValues() 請求加密強度的隨機值。Web Crypto 實作應使用以主機環境提供的高品質熵種子化的加密安全偽隨機數產生器。實務上，瀏覽器將此責任委託給作業系統設施與平台加密提供者。

PwdGen 不聲稱每次密碼生成呼叫都直接取樣硬體雜訊源。更安全且準確的說法是，瀏覽器透過 Web Crypto API 提供 CSPRNG 輸出，且 PwdGen 避免使用非加密的偽隨機介面。

為何不使用 Math.random()

Math.random() 並非為安全敏感用途而設計。它適用於模擬、視覺效果與一般隨機化 UI 行為，但無法提供密碼、重設碼、簽章金鑰或其他憑證所需的保證。

PwdGen 將不安全的偽隨機備援視為失敗狀態。若 Web Crypto 不可用，生成器應顯示相容性錯誤，而非默默產生弱憑證。

拒絕採樣

隨機位元組與整數通常從 2 的冪次範圍中抽取。密碼字母集的大小很少能整除該範圍。直接取模運算可能使某些字元出現機率略高。

PwdGen 使用拒絕採樣：

抽取一個 32 位元無號整數。
計算在 32 位元範圍內，字母集大小的最大倍數。
拒絕超過該邊界的值。
僅對剩餘的完整範圍套用取模。

這使得有界字元選擇保持均勻，而不引入可測量的取模偏差。

字元覆蓋與熵

對於設定的密碼策略，生成器先從每個啟用的類別中選取一個字元，再從合併的字母集中填滿其餘位置，最後對結果進行洗牌。這有助於滿足目標密碼規則，而不將可預測的類別放在可預測的位置。

理論熵估計值為：

bits = length × log2(uniqueAlphabetSize)

該值是從設定字母集中均勻隨機選擇的上限。它不考慮密碼重複使用、使用者編輯輸出、受損裝置、洩漏密碼或目標服務的弱儲存。

隱私邊界

在瀏覽器工具中，生成的值保留在頁面記憶體與可見的結果欄位中，直到使用者複製或匯出。本地生成器不會將生成的密碼傳送至 PwdGen 伺服器、放入 URL 或寫入分析事件。

此邊界無法防範惡意瀏覽器擴充功能、剪貼簿管理員、作業系統受損、螢幕擷取、釣魚頁面，或使用者將生成的密碼貼到不安全的目的地。

可重現實作

公開的 pwdgen-cli 套件與預先準備的 pwdgen-core 套件旨在讓生成模型可在網頁之外被檢視。單元測試涵蓋字元類別包含、排除字元、無效設定、熵公式，以及缺乏不安全偽隨機備援程式碼路徑的情況。

目標並非使 PwdGen 成為私有標準。目標是讓實作足夠小，使開發人員能夠閱讀、測試並在環境需要不同信任邊界時替換它。