Pythonのsecretsモジュール詳細解説：安全なパスワードとトークン生成の鍵🔑

secrets.choice(sequence)

空でないシーケンス（リスト、タプル、文字列など）から、ランダムに要素を1つ選択して返します。random.choice() のセキュア版です。

import secrets
import string

alphabet = string.ascii_letters + string.digits  # 英大小文字 + 数字
secure_char = secrets.choice(alphabet)
print(f"安全に選ばれた文字: {secure_char}")

colors = ["Red", "Green", "Blue", "Yellow"]
secure_color = secrets.choice(colors)
print(f"安全に選ばれた色: {secure_color}")

secrets.randbelow(exclusive_upper_bound)

0以上 exclusive_upper_bound 未満のランダムな整数を返します。つまり、[0, n) の範囲で整数を生成します。random.randrange(n) のセキュア版と考えることができます。

import secrets

# 0以上100未満 (0-99) の安全な乱数を生成
secure_int = secrets.randbelow(100)
print(f"0から99までの安全な乱数: {secure_int}")

# サイコロの目を安全に生成 (1-6)
# randbelow(6) は 0-5 を返すので +1 する
dice_roll = secrets.randbelow(6) + 1
print(f"安全なサイコロの目: {dice_roll}")

注意: randbelow(0) は ValueError を発生させます。

secrets.randbits(k)

k ビットのランダムな非負整数を返します。生成される値の範囲は [0, 2^k - 1] です。

import secrets

# 8ビットのランダムな整数 (0-255)
random_8bit = secrets.randbits(8)
print(f"8ビットの安全な乱数: {random_8bit} (2進数: {random_8bit:08b})")

# 128ビットのランダムな整数
random_128bit = secrets.randbits(128)
print(f"128ビットの安全な乱数 (一部): ...{random_128bit % (10**10)}") # 大きすぎるので下位10桁を表示

secrets.token_bytes([nbytes=None])

指定されたバイト数 (nbytes) のランダムなバイト文字列を返します。nbytes が省略された場合や None の場合は、適切なデフォルト値（現在は32バイトですが、将来変更される可能性があります）が使用されます。

import secrets

# 16バイトのランダムなバイト列を生成
byte_token = secrets.token_bytes(16)
print(f"16バイトのトークン: {byte_token}")

# デフォルトのバイト数で生成
default_byte_token = secrets.token_bytes()
print(f"デフォルト長のトークン ({len(default_byte_token)}バイト): {default_byte_token[:8]}...") # 長いので一部表示

バイナリデータの扱いに適しています。

secrets.token_hex([nbytes=None])

指定されたバイト数 (nbytes) のランダムなバイト列を生成し、それを16進数表現の文字列に変換して返します。結果の文字列長は nbytes の2倍になります（1バイト = 16進数2文字）。nbytes が省略または None の場合はデフォルト値が使われます。

import secrets

# 16バイト相当の16進数トークン (32文字) を生成
hex_token = secrets.token_hex(16)
print(f"16進数トークン (32文字): {hex_token}")

# デフォルト長で生成
default_hex_token = secrets.token_hex()
print(f"デフォルト長の16進数トークン ({len(default_hex_token)}文字): {default_hex_token[:16]}...")

APIキーやデバッグ用のIDなど、印字可能なランダム文字列が必要な場合に便利です。

secrets.token_urlsafe([nbytes=None])

指定されたバイト数 (nbytes) のランダムなバイト列を生成し、それをURLセーフなBase64エンコーディングで文字列に変換して返します。URLセーフとは、URL内で特別な意味を持たない文字（英大小文字、数字、-、_）のみで構成されることを意味します。パディング文字 = は含まれません。結果の文字列長は、nbytes の約 4/3 倍になります。nbytes が省略または None の場合はデフォルト値が使われます。

import secrets

# 16バイト相当のURLセーフトークン (約22文字) を生成
urlsafe_token = secrets.token_urlsafe(16)
print(f"URLセーフトークン (約22文字): {urlsafe_token}")

# デフォルト長で生成
default_urlsafe_token = secrets.token_urlsafe()
print(f"デフォルト長のURLセーフトークン ({len(default_urlsafe_token)}文字): {default_urlsafe_token[:16]}...")

パスワードリセットトークン、一時的なURL、セッションIDなど、URLの一部として埋め込んだり、HTTPヘッダーで送信したりするのに非常に適しています。

secrets.compare_digest(a, b)

2つの文字列 (またはバイト列) a と b を比較し、完全に一致すれば True、そうでなければ False を返します。この関数の最大の特徴は、「定数時間比較 (Constant-Time Comparison)」を行う点にあります。

通常の文字列比較演算子 (==) は、文字列の先頭から比較していき、異なる文字が見つかった時点、あるいはどちらかの文字列の終端に達した時点で比較を終了します（短絡評価）。これは効率的ですが、比較にかかる時間が比較対象の文字列の内容によって変動するという性質を持ちます。

攻撃者は、この比較時間の微妙な差を多数回計測・分析することで、パスワードやトークンなどの秘密情報を推測しようと試みることがあります。これを「タイミング攻撃 (Timing Attack)」と呼びます。

secrets.compare_digest() は、比較対象の文字列の内容に関わらず、常に同じくらいの時間をかけて比較処理を行います。これにより、タイミング攻撃のリスクを大幅に軽減できます。

import secrets
import hmac # compare_digest は hmac モジュールにも同じものがあります

user_input_token = "some_token_from_user"
correct_token = "some_token_from_user" # 本来は安全に生成・保存されたもの
correct_token_bytes = correct_token.encode('utf-8')
user_input_token_bytes = user_input_token.encode('utf-8')

# 安全な比較
if secrets.compare_digest(correct_token_bytes, user_input_token_bytes):
    print("トークンが一致しました (安全な比較)")
else:
    print("トークンが一致しません (安全な比較)")

# 不安全な比較 (==) - タイミング攻撃のリスクあり
# if correct_token_bytes == user_input_token_bytes:
#     print("トークンが一致しました (不安全な比較)")

wrong_token = "wrong_token_from_user"
wrong_token_bytes = wrong_token.encode('utf-8')

if not secrets.compare_digest(correct_token_bytes, wrong_token_bytes):
    print("異なるトークンは正しく False と判定されます (安全な比較)")

# 注意: 比較するaとbは同じ型 (str または bytes) である必要があります。
# また、strの場合はASCII文字のみであるべきです。通常はbytes型で比較します。
# secrets.compare_digest(correct_token, correct_token_bytes) # これは TypeError になります

ユーザーからの入力値（パスワード、トークンなど）と、システムに保存されている正しい値を比較する際には、必ず secrets.compare_digest() を使用してください。

(注: secrets.compare_digest は内部的には hmac.compare_digest へのエイリアスです)

import secrets
import string

def generate_secure_password(length=12):
    """指定された長さの安全なパスワードを生成する"""
    if length < 8:
        print("警告: パスワード長は8文字以上を推奨します。")

    # パスワードに使用する文字セット
    letters = string.ascii_letters  # a-z, A-Z
    digits = string.digits          # 0-9
    symbols = string.punctuation    # !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

    # 全ての文字種を含む文字セットを作成
    all_characters = letters + digits + symbols

    while True:
        password = ''.join(secrets.choice(all_characters) for _ in range(length))
        # パスワードが全ての文字種（大文字、小文字、数字、記号）を少なくとも1つ含むか確認
        if (any(c in string.ascii_lowercase for c in password)
                and any(c in string.ascii_uppercase for c in password)
                and any(c in digits for c in password)
                and any(c in symbols for c in password)):
            return password

# パスワード生成の例
password_16 = generate_secure_password(16)
print(f"生成された16文字のパスワード: {password_16}")

password_10 = generate_secure_password(10)
print(f"生成された10文字のパスワード: {password_10}")

# 短いパスワードも生成できるが、警告が出る
password_6 = generate_secure_password(6)
print(f"生成された6文字のパスワード: {password_6}")

この関数は、指定された長さになるまでランダムな文字を選び、生成されたパスワードが全ての文字種（大文字、小文字、数字、記号）を含んでいるかを確認します。条件を満たすまでパスワード生成を繰り返すため、確実に要件を満たすパスワードが得られます。

import secrets
from urllib.parse import urlencode

def generate_password_reset_link(base_url, user_id):
    """パスワードリセット用のURLを生成する"""
    # 32バイト (256ビット) のURLセーフトークンを生成 (十分な強度)
    token = secrets.token_urlsafe(32)

    # トークンとユーザーIDをデータベースに一時的に保存する処理 (ここでは省略)
    # save_reset_token(user_id, token, expires_in=3600) # 例: 1時間有効

    # URLパラメータを構築
    params = {'token': token, 'uid': user_id}
    query_string = urlencode(params)

    # 完全なURLを組み立て
    reset_link = f"{base_url}?{query_string}"
    return reset_link, token # URLと、検証用にトークン自体も返す (DB保存しない場合)

# 使用例
base_reset_url = "https://example.com/reset-password"
user_id_to_reset = 12345

generated_link, generated_token = generate_password_reset_link(base_reset_url, user_id_to_reset)
print(f"生成されたパスワードリセットリンク:\n{generated_link}")

# --- ユーザーがリンクをクリックし、サーバー側で検証する際の処理 (イメージ) ---
received_token = "some_token_from_url" # URLから受け取ったトークン
received_uid = 12345 # URLから受け取ったユーザーID

# DBからトークンを取得 (または生成時に返されたトークンと比較)
# correct_token = get_reset_token_from_db(received_uid)
correct_token = generated_token # DBを使わない場合の例

if correct_token and secrets.compare_digest(correct_token, received_token):
    print("\nトークン検証成功！ パスワード再設定画面へ遷移します。")
    # パスワード再設定処理へ
    # delete_reset_token(received_uid) # 使用済みトークンを削除
else:
    print("\nトークンが無効か期限切れです。")
    # エラー処理

token_urlsafe() を使うことで、URLにそのまま埋め込める安全なトークンが簡単に生成できます。検証時には必ず compare_digest() を使いましょう。

import secrets

def generate_api_key(length_bytes=32):
    """指定されたバイト長のAPIキー (16進数文字列) を生成する"""
    # token_hex はバイト長の2倍の文字列を返す
    api_key = secrets.token_hex(length_bytes)
    return api_key

# 32バイト (256ビット) 相当のAPIキーを生成 (64文字の16進数)
api_key_256bit = generate_api_key(32)
print(f"生成されたAPIキー (256ビット相当): {api_key_256bit}")

# 16バイト (128ビット) 相当のAPIキーを生成 (32文字の16進数)
api_key_128bit = generate_api_key(16)
print(f"生成されたAPIキー (128ビット相当): {api_key_128bit}")

token_hex() は、可読性が求められる場合に適しています。強度を保つために十分なバイト数を指定することが重要です。