安全指南

以 Web Crypto 與拒絕取樣實作的用戶端密碼產生白皮書

說明 PwdGen 在瀏覽器本機產生密碼時的隨機來源、拒絕取樣、熵值邊界與隱私邊界。

摘要

PwdGen 的用戶端參考產生方法包含三個步驟：由瀏覽器或執行環境的 Web Crypto 提供隨機值，以拒絕取樣將隨機值映射為無偏的有限範圍索引，再用 Fisher-Yates 洗牌把必要字元類別分散到最終密碼中。這個方法刻意保持小而清楚，方便審查，也能在網頁、API 適配層、CLI 與準備中的 pwdgen-core 套件之間重現。

本文是工程說明，不宣稱創造新的密碼學原語，也不宣稱已成為產業標準或完成第三方安全稽核。

隨機來源

產生器透過 crypto.getRandomValues() 取得密碼學強隨機值。Web Crypto 實作通常使用由宿主環境高品質熵源播種的密碼學安全偽隨機數產生器。實際瀏覽器會把底層隨機性委託給作業系統與平台加密能力。

PwdGen 不宣稱每一次產生都會直接讀取 CPU 硬體噪聲源。較準確的說法是：瀏覽器透過 Web Crypto API 提供 CSPRNG 輸出，而 PwdGen 避免使用非密碼學用途的偽隨機介面。

為什麼不用一般隨機數

Math.random() 這類一般腳本隨機數並不是為安全場景設計。它適合模擬、動畫與一般 UI 隨機行為，但不適合作為密碼、重設碼、簽章密鑰或其他憑證的隨機來源。

如果目前環境沒有 Web Crypto，PwdGen 應顯示相容性錯誤，而不是悄悄退回弱隨機數並產生看似可用的密碼。

拒絕取樣

隨機整數通常來自 2 的冪次範圍，而密碼字元集大小很少剛好整除該範圍。如果直接取模，某些字元會比其他字元略微更容易出現。

PwdGen 使用拒絕取樣：

讀取一個 32 位元無符號整數。
計算 32 位元範圍內可被字元集大小整除的最大邊界。
丟棄超過邊界的值。
只對完整範圍內的值取模。

這能讓每個字元被選中的機率保持一致，避免取模偏差。

字元覆蓋與理論熵

對於有密碼規則限制的場景，產生器會先從每個啟用字元類別中選取一個字元，再從合併字元集中填滿剩餘位置，最後進行洗牌。這能滿足常見密碼策略，同時避免某一類字元總是出現在固定位置。

理論熵估算公式為：

bits = length × log2(uniqueAlphabetSize)

這個數值是「從指定字元集均勻隨機選擇」時的理論上限。它不代表密碼被外洩、重複使用、手動修改、裝置被入侵或目標服務儲存方式不安全時仍然安全。

隱私邊界

在瀏覽器本機工具中，產生值只存在於頁面記憶體和可見結果區域，直到使用者複製或匯出。PwdGen 的本機產生器不會把產生密碼送到伺服器，不會寫入 URL，也不會寫入分析事件。

這個邊界無法防禦惡意瀏覽器擴充功能、剪貼簿管理器、作業系統被入侵、螢幕錄製、釣魚頁面，或使用者把密碼貼到不可信服務中。

可重現實作

公開的 pwdgen-cli 套件和準備中的 pwdgen-core 套件用於讓產生模型離開網頁後仍可檢查。測試涵蓋字元類別、排除字元、無效設定、熵公式，以及不使用弱隨機退回路徑。

目標不是把 PwdGen 宣稱為私有標準，而是讓實作足夠小、足夠透明，方便開發者閱讀、測試，並在自己的信任邊界需要變更時替換。