Python 庫手冊：secrets 安全隨機密碼模塊

secrets 是 Python 3.6+ 引入的標準庫模塊，專爲生成密碼學安全的隨機數、令牌和密碼而設計。它在底層使用操作系統提供的高質量隨機源（如 /dev/urandom 或 Windows 的 CryptGenRandom），適用於身份驗證、密鑰生成、驗證碼、口令管理等安全敏感場景。

常見應用場景：

（1）生成隨機密碼、驗證碼、密鑰（key）。

（2）創建唯一令牌（如用戶登錄 token）。

（3）生成不可預測的 URL 安全字符串（適合郵箱驗證、重置鏈接等）。

（4）隨機選擇安全選項（如加密中使用的算法）。

◆ ◆ ◆

核心概念

1、加密安全隨機生成

相比 random 模塊，secrets 使用的是更適合安全場景的加密強度隨機源。

2、專用於敏感數據生成

不適合用於普通模擬或遊戲用途（請用 random 模塊）。

3、支持二進制和字符串格式的令牌

如 token_bytes()、token_hex()、token_urlsafe()，可適應不同需求。

4、安全選擇與密碼構造

提供 choice() 方法安全地從字符集中選取字符，適合構建密碼或口令。

◆ ◆ ◆

應用舉例

例 1：生成隨機安全整數（在給定範圍內）

例 2：生成隨機 URL 安全的令牌

例 3：從字符集中安全選擇一個字符（如密碼生成）

例 4：使用 token_bytes() 生成二進制密鑰（用於加密）

例 5：生成唯一邀請碼（避免重複）

◆ ◆ ◆

常用函數速覽

secrets.choice(sequence)

從序列中安全隨機選擇一個元素。

參數：

sequence：非空序列（如字符串、列表等）

返回：隨機選中的元素

secrets.compare_digest(a, b)

安全比較兩個字符串或字節，防止時序攻擊。

參數：

a, b：要比較的對象（str 或 bytes）

返回：bool，相同爲 True

secrets.randbelow(n)

返回小於 n 的非負隨機整數。

參數：

n：正整數上限

返回：int

secrets.randbits(k)

返回一個具有 k 位隨機二進制數的整數。

參數：

k：位數（整數）

返回：int

secrets.token_bytes(nbytes=None)

生成安全的隨機字節串。

參數：

nbytes：要生成的字節數，默認 32

返回：bytes

secrets.token_hex(nbytes=None)

生成安全的隨機十六進制字符串。

參數：

nbytes：對應生成多少字節（每字節 = 2 位十六進制字符），默認 32

返回：str（如 '9f8c7a6d...'）

secrets.token_urlsafe(nbytes=None)

生成 URL 安全的 Base64 編碼字符串（適合鏈接使用）。

參數：

nbytes：原始字節數，默認 32

返回：str，適合 URL 傳輸的 token

◆ ◆ ◆

補充說明

1、secrets 是生成敏感數據（如密碼或 token）的首選模塊，請勿使用 random 生成密碼。

2、secrets.choice() 可替代 random.choice()，用於更安全的場景。

3、token_urlsafe() 生成的字符串包含 A-Z, a-z, 0-9, -, _，可以安全嵌入 URL。

“點贊有美意，讚賞是鼓勵”