金鑰雜湊與資料驗證技術：HMAC 實戰與時序攻擊防禦

# 匯入 hashlib 模組
# 該模組提供多種密碼學雜湊函式的實作
import hashlib

# 建立 SHA-256 雜湊物件
# 參數是要進行雜湊的位元組資料
# 注意必須傳入位元組而非字串
hash_function = hashlib.sha256(b'message')

# 查詢雜湊函式的輸出大小（以位元組為單位）
# SHA-256 的輸出大小固定為 32 位元組
# 這個大小不會隨輸入資料的大小而改變
digest_size = hash_function.digest_size
print(f'雜湊值大小: {digest_size} 位元組')

# 取得雜湊值的原始位元組表示
# 然後計算其位元長度
# 32 位元組乘以 8 等於 256 位元
digest = hash_function.digest()
bit_length = len(digest) * 8
print(f'雜湊值位元長度: {bit_length} 位元')

# 取得雜湊值的十六進位表示
# 這種格式更易於閱讀和傳輸
# 每個位元組會轉換為兩個十六進位字元
hex_digest = hash_function.hexdigest()
print(f'雜湊值（十六進位）: {hex_digest}')

# 使用 update 方法可以分段處理大型資料
# 這對於處理大檔案特別有用
hash_function_2 = hashlib.sha256()
hash_function_2.update(b'first part ')
hash_function_2.update(b'second part')
print(f'分段計算的雜湊值: {hash_function_2.hexdigest()}')

# 匯入 zlib 模組
# 該模組提供壓縮功能和校驗和計算
import zlib

# 建立一個包含重複內容的測試訊息
# 重複的內容可以展示壓縮的效果
message = b'this is repetitious content ' * 42

# 計算訊息的 CRC-32 校驗和
# CRC-32 產生一個 32 位元的校驗值
checksum = zlib.crc32(message)
print(f'CRC-32 校驗和: {checksum}')

# 壓縮訊息並解壓縮
# 展示校驗和在資料處理流程中的應用
compressed = zlib.compress(message)
decompressed = zlib.decompress(compressed)

# 驗證解壓縮後的資料是否與原始資料相同
# 透過比較 CRC-32 校驗和來進行驗證
is_valid = zlib.crc32(decompressed) == checksum
print(f'資料驗證結果: {is_valid}')

# 注意：CRC-32 不具備密碼學安全性
# 攻擊者可以構造碰撞
# 絕對不要用於安全相關的應用

# 匯入 os 模組
import os

# 使用 os.urandom 生成 16 個隨機位元組
# 16 位元組等於 128 位元
# 這提供了足夠的安全強度
random_bytes = os.urandom(16)
print(f'隨機位元組: {random_bytes}')
print(f'位元組長度: {len(random_bytes)}')

# 將隨機位元組轉換為十六進位字串
# 這樣更容易閱讀和儲存
hex_string = random_bytes.hex()
print(f'十六進位表示: {hex_string}')

# 從 secrets 模組匯入令牌生成函式
from secrets import token_bytes, token_hex, token_urlsafe

# 生成 32 位元組的隨機金鑰（原始位元組格式）
# 32 位元組等於 256 位元的熵
# 適用於需要二進位金鑰的場景，如加密演算法
raw_key = token_bytes(32)
print(f'原始位元組金鑰: {raw_key}')
print(f'金鑰長度: {len(raw_key)} 位元組')

# 生成 32 位元組的隨機金鑰（十六進位格式）
# 輸出長度為 64 個字元
# 每個位元組轉換為 2 個十六進位字元
# 適用於需要純文字格式儲存的場景
hex_key = token_hex(32)
print(f'十六進位金鑰: {hex_key}')
print(f'字串長度: {len(hex_key)} 字元')

# 生成 32 位元組的隨機金鑰（URL 安全格式）
# 使用 Base64 編碼，但以 - 和 _ 取代 + 和 /
# 輸出只包含英數字和 -_ 符號
# 適用於需要在 URL 或檔案名稱中使用的場景
url_safe_key = token_urlsafe(32)
print(f'URL 安全金鑰: {url_safe_key}')

from pathlib import Path
import secrets
import math

# 從系統字典檔案載入單詞列表
# 在 macOS 和 Linux 系統上
# 這個檔案通常位於 /usr/share/dict/words
# 包含數萬個英文單詞
dict_path = Path('/usr/share/dict/words')
words = dict_path.read_text().splitlines()

# 過濾單詞列表
# 移除太短或太長的單詞
# 移除包含撇號或其他特殊字元的單詞
# 這樣可以產生更容易輸入的密碼短語
filtered_words = [
    word.lower() for word in words
    if 4 <= len(word) <= 8 and word.isalpha()
]
print(f'過濾後的字典大小: {len(filtered_words)} 個單詞')

# 使用 secrets.choice 從單詞列表中隨機選取
# 選取 6 個單詞組成密碼短語
# 以空格分隔各個單詞
word_count = 6
passphrase = ' '.join(
    secrets.choice(filtered_words)
    for _ in range(word_count)
)
print(f'生成的密碼短語: {passphrase}')

# 計算密碼短語的理論熵值
# 熵值 = log2(字典大小) * 單詞數量
entropy_per_word = math.log2(len(filtered_words))
total_entropy = entropy_per_word * word_count
print(f'每個單詞的熵: {entropy_per_word:.2f} 位元')
print(f'密碼短語總熵: {total_entropy:.2f} 位元')

# 從 hashlib 匯入 blake2b 雜湊函式
from hashlib import blake2b

# 定義要進行雜湊的訊息
message = b'This is a secret message'

# 定義兩個不同的金鑰
# 金鑰長度最多可以是 64 位元組
key_alice = b'alice_secret_key_12345'
key_bob = b'bob_secret_key_67890'

# 使用 Alice 的金鑰對訊息進行雜湊
# 產生的雜湊值只有知道 Alice 金鑰的人才能產生
hash_alice_1 = blake2b(message, key=key_alice).digest()
hash_alice_2 = blake2b(message, key=key_alice).digest()

# 驗證相同金鑰產生相同雜湊值
print(f'相同金鑰產生相同雜湊值: {hash_alice_1 == hash_alice_2}')

# 使用 Bob 的金鑰對相同訊息進行雜湊
# 由於金鑰不同，產生的雜湊值也會不同
hash_bob = blake2b(message, key=key_bob).digest()

# 驗證不同金鑰產生不同雜湊值
print(f'不同金鑰產生不同雜湊值: {hash_alice_1 != hash_bob}')

# 展示雜湊值的十六進位表示
print(f'Alice 的雜湊值: {hash_alice_1.hex()[:32]}...')
print(f'Bob 的雜湊值: {hash_bob.hex()[:32]}...')

import hashlib
from pathlib import Path
import hmac

def store_file(path, data, key):
    """
    儲存資料及其金鑰雜湊值到檔案系統

    這個函式會將資料寫入指定路徑
    並在相同位置建立一個副檔名為 .mac 的檔案
    儲存資料的訊息認證碼

    參數:
        path: 資料檔案的路徑
        data: 要儲存的位元組資料
        key: 用於計算訊息認證碼的金鑰
    """
    # 建立資料檔案和認證碼檔案的路徑物件
    data_path = Path(path)
    mac_path = data_path.with_suffix('.mac')

    # 使用 BLAKE2b 計算資料的金鑰雜湊值
    # digest_size 參數指定輸出長度為 32 位元組
    # 這與 SHA-256 的輸出長度相同
    mac_value = hashlib.blake2b(
        data,
        key=key,
        digest_size=32
    ).hexdigest()

    # 寫入資料檔案和認證碼檔案
    # 使用 write_bytes 寫入二進位資料
    # 使用 write_text 寫入文字格式的認證碼
    data_path.write_bytes(data)
    mac_path.write_text(mac_value)

    print(f'檔案已儲存: {data_path}')
    print(f'認證碼已儲存: {mac_path}')

def verify_file(path, key):
    """
    驗證檔案是否被修改

    這個函式會讀取指定路徑的檔案
    重新計算其訊息認證碼
    並與儲存的認證碼進行比較

    參數:
        path: 資料檔案的路徑
        key: 用於計算訊息認證碼的金鑰

    返回:
        如果檔案未被修改則返回 True
        如果檔案已被修改則返回 False
    """
    # 建立資料檔案和認證碼檔案的路徑物件
    data_path = Path(path)
    mac_path = data_path.with_suffix('.mac')

    # 讀取儲存的資料和原始認證碼
    data = data_path.read_bytes()
    stored_mac = mac_path.read_text()

    # 重新計算資料的訊息認證碼
    computed_mac = hashlib.blake2b(
        data,
        key=key,
        digest_size=32
    ).hexdigest()

    # 使用 hmac.compare_digest 進行安全比較
    # 這可以防禦時序攻擊
    is_valid = hmac.compare_digest(computed_mac, stored_mac)

    if is_valid:
        print(f'檔案驗證成功: {data_path}')
    else:
        print(f'警告：檔案可能已被竄改: {data_path}')

    return is_valid

import hashlib
import hmac

# 建立 HMAC-SHA256 物件
# 第一個參數是金鑰（必須是位元組）
# msg 參數是要認證的訊息
# digestmod 參數指定底層使用的雜湊函式
hmac_sha256 = hmac.new(
    key=b'my_secret_key',
    msg=b'message to authenticate',
    digestmod=hashlib.sha256
)

# 取得訊息認證碼的原始位元組表示
mac_bytes = hmac_sha256.digest()
print(f'認證碼（位元組）: {mac_bytes}')

# 取得訊息認證碼的十六進位表示
# 這種格式更適合儲存和傳輸
mac_hex = hmac_sha256.hexdigest()
print(f'認證碼（十六進位）: {mac_hex}')

# 查詢認證碼的大小
# HMAC-SHA256 的輸出是 32 位元組
mac_size = hmac_sha256.digest_size
print(f'認證碼大小: {mac_size} 位元組')

# 使用 update 方法可以分段處理大型訊息
hmac_obj = hmac.new(b'key', digestmod=hashlib.sha256)
hmac_obj.update(b'first part ')
hmac_obj.update(b'second part')
print(f'分段計算的認證碼: {hmac_obj.hexdigest()}')

import hashlib
import hmac
import json
from typing import Optional

def send_authenticated_message(shared_key: bytes, message: bytes) -> bytes:
    """
    使用共享金鑰對訊息進行認證並打包

    這個函式會計算訊息的 HMAC-SHA256 認證碼
    並將訊息和認證碼打包成 JSON 格式
    便於透過網路傳輸

    參數:
        shared_key: 發送方和接收方共享的密鑰
        message: 要發送的訊息（位元組格式）

    返回:
        包含訊息和認證碼的 JSON 編碼資料
    """
    # 建立 HMAC-SHA256 物件
    # 使用共享金鑰和 SHA-256 雜湊函式
    hmac_obj = hmac.new(
        key=shared_key,
        msg=message,
        digestmod=hashlib.sha256
    )

    # 取得認證碼的十六進位表示
    mac_value = hmac_obj.hexdigest()

    # 將訊息和認證碼打包成字典
    # 訊息轉換為列表以便 JSON 序列化
    authenticated_msg = {
        'message': list(message),
        'mac': mac_value,
    }

    # 序列化為 JSON 並編碼為位元組
    return json.dumps(authenticated_msg).encode('utf-8')

def receive_authenticated_message(
    shared_key: bytes,
    data: bytes
) -> Optional[bytes]:
    """
    驗證收到的已認證訊息

    這個函式會解析收到的資料
    重新計算訊息的認證碼
    並與收到的認證碼進行比較

    參數:
        shared_key: 發送方和接收方共享的密鑰
        data: 收到的 JSON 編碼資料

    返回:
        如果驗證成功則返回訊息內容
        如果驗證失敗則返回 None
    """
    # 解析 JSON 資料
    authenticated_msg = json.loads(data.decode('utf-8'))

    # 還原訊息的位元組格式
    message = bytes(authenticated_msg['message'])
    received_mac = authenticated_msg['mac']

    # 使用相同的金鑰重新計算認證碼
    hmac_obj = hmac.new(
        key=shared_key,
        msg=message,
        digestmod=hashlib.sha256
    )
    computed_mac = hmac_obj.hexdigest()

    # 使用 compare_digest 進行安全比較
    # 這可以防禦時序攻擊
    if hmac.compare_digest(computed_mac, received_mac):
        print('訊息認證成功')
        print(f'訊息內容: {message.decode("utf-8")}')
        return message
    else:
        print('警告：訊息認證失敗')
        print('訊息可能已被竄改或來源不可信')
        return None

# 使用範例
# 假設 Alice 和 Bob 已經透過安全方式交換了共享金鑰
shared_key = b'this_is_a_shared_secret_key_32b!'
message = b'Hello Alice, this is Bob!'

# Bob 發送已認證的訊息
print('=== Bob 發送訊息 ===')
outbound_data = send_authenticated_message(shared_key, message)

# Alice 接收並驗證訊息
print('\n=== Alice 驗證訊息 ===')
verified_message = receive_authenticated_message(shared_key, outbound_data)

import hmac
import time

def insecure_compare(a: str, b: str) -> bool:
    """
    不安全的字串比較（僅用於展示，請勿在實際應用中使用）

    這個函式使用短路比較
    一旦發現不相符就立即返回
    這會導致時間洩漏
    """
    if len(a) != len(b):
        return False
    for i in range(len(a)):
        if a[i] != b[i]:
            return False
    return True

def secure_compare(a: str, b: str) -> bool:
    """
    安全的字串比較

    使用 hmac.compare_digest 進行固定時間比較
    無論輸入是否相同，比較時間都相同
    這可以防禦時序攻擊
    """
    return hmac.compare_digest(a, b)

# 展示時序攻擊的原理
# 注意：實際的時序攻擊需要更精確的時間測量
# 以及大量的樣本來消除雜訊
correct_mac = 'a1b2c3d4e5f6g7h8'

# 測試不安全比較的時間差異
test_cases = [
    'x1b2c3d4e5f6g7h8',  # 第一個字元不同
    'a1x2c3d4e5f6g7h8',  # 第三個字元不同
    'a1b2c3d4e5f6g7x8',  # 倒數第二個字元不同
    'a1b2c3d4e5f6g7h8',  # 完全相同
]

print('不安全比較的時間測量（僅供展示）：')
for test in test_cases:
    start = time.perf_counter_ns()
    for _ in range(10000):
        insecure_compare(correct_mac, test)
    elapsed = time.perf_counter_ns() - start
    print(f'  {test}: {elapsed} ns')

print('\n安全比較（使用 compare_digest）：')
for test in test_cases:
    start = time.perf_counter_ns()
    for _ in range(10000):
        secure_compare(correct_mac, test)
    elapsed = time.perf_counter_ns() - start
    print(f'  {test}: {elapsed} ns')