加密与编码工具：hashlib、hmac 与 base64

import hashlib

# ========== 方式一：单次计算（适合小数据） ==========
# 直接对字节串计算哈希
text = "Hello, Python 哈希世界！"
digest = hashlib.sha256(text.encode('utf-8')).hexdigest()
print(f"SHA-256: {digest}")
# 输出: 64个十六进制字符的固定长度字符串

# ========== 方式二：分块更新（适合大文件） ==========
# 对于大文件，分块读取并逐步更新哈希对象
hasher = hashlib.sha256()
hasher.update(b"Hello, ")       # 第一块
hasher.update(b"Python ")       # 第二块
hasher.update(b"World!")        # 第三块
# 最终结果与一次性计算 b"Hello, Python World!" 完全相同
print(f"分块 SHA-256: {hasher.hexdigest()}")

# ========== 方式三：使用 new() 工厂函数 ==========
# 通过算法名称字符串动态选择算法
algo = "sha512"
hasher = hashlib.new(algo)
hasher.update(b"some data")
print(f"{algo}: {hasher.hexdigest()}")

import hashlib

# 查看当前平台支持的所有算法
print("可用算法:", hashlib.algorithms_available)
# 输出: {'sha256', 'sha512', 'md5', 'sha3_256', 'blake2b', ...}

# 查看在所有平台上保证可用的算法
print("保证可用:", hashlib.algorithms_guaranteed)
# 输出: {'sha256', 'sha384', 'sha224', 'sha512', 'sha1', 'md5', ...}

import hashlib

def file_checksum(filepath: str, algorithm: str = "sha256") -> str:
    """
    计算文件的哈希校验值，用于验证文件完整性。

    Args:
        filepath: 文件路径
        algorithm: 哈希算法名称（sha256, sha512, md5 等）

    Returns:
        十六进制哈希字符串
    """
    hasher = hashlib.new(algorithm)
    with open(filepath, "rb") as f:
        # 每次读取 64KB，避免大文件撑爆内存
        while chunk := f.read(65536):
            hasher.update(chunk)
    return hasher.hexdigest()

# 使用示例
# checksum = file_checksum("ubuntu-24.04.iso", "sha256")
# print(f"文件 SHA-256: {checksum}")
# 将结果与官网公布的校验值比对，一致则说明文件未被篡改

import hashlib
import os
import hmac

def hash_password(password: str, iterations: int = 100_000) -> bytes:
    """
    使用 PBKDF2-HMAC-SHA256 和随机盐安全地哈希密码。

    Args:
        password: 用户输入的明文密码
        iterations: PBKDF2 迭代次数（推荐 ≥ 100000）

    Returns:
        salt(16字节) + hash(32字节) 的拼接字节串
    """
    # 1. 生成 16 字节（128 位）的密码学安全随机盐
    salt = os.urandom(16)

    # 2. 使用 PBKDF2-HMAC-SHA256 进行密钥派生
    hashed = hashlib.pbkdf2_hmac(
        'sha256',                        # 底层哈希算法
        password.encode('utf-8'),        # 密码转为字节
        salt,                            # 随机盐
        iterations                       # 迭代次数
    )

    # 3. 将盐和哈希值拼接存储（验证时需要原始盐）
    return salt + hashed


def verify_password(stored: bytes, provided_password: str, iterations: int = 100_000) -> bool:
    """
    验证提供的密码是否与存储的哈希匹配。

    Args:
        stored: hash_password() 返回的存储值
        provided_password: 用户登录时输入的密码
        iterations: 必须与 hash_password 时使用的迭代次数一致

    Returns:
        True 表示密码正确
    """
    # 1. 从存储值中分离盐和原始哈希
    salt = stored[:16]           # 前 16 字节是盐
    original_hash = stored[16:]  # 后面是哈希值

    # 2. 使用相同的盐和迭代次数重新计算哈希
    new_hash = hashlib.pbkdf2_hmac(
        'sha256',
        provided_password.encode('utf-8'),
        salt,
        iterations
    )

    # 3. 使用 hmac.compare_digest 安全比较（防止时序攻击）
    return hmac.compare_digest(original_hash, new_hash)


# --- 使用示例 ---
password = "My-S3cr3t-P@ssw0rd!"
stored = hash_password(password)
print(f"存储值 (盐+哈希): {stored.hex()}")

print(f"正确密码验证: {verify_password(stored, 'My-S3cr3t-P@ssw0rd!')}")  # True
print(f"错误密码验证: {verify_password(stored, 'wrong-password')}")       # False

import hmac
import hashlib

# 共享密钥（双方事先约定，必须保密）
SECRET_KEY = b'my-super-secret-key-change-in-production'

def sign_message(message: bytes) -> str:
    """
    发送方：为消息生成 HMAC 签名。

    Args:
        message: 待发送的消息（字节串）

    Returns:
        十六进制签名字符串
    """
    h = hmac.new(SECRET_KEY, message, hashlib.sha256)
    return h.hexdigest()


def verify_message(message: bytes, signature: str) -> bool:
    """
    接收方：验证消息的 HMAC 签名。

    Args:
        message: 收到的消息（字节串）
        signature: 收到的十六进制签名字符串

    Returns:
        True 表示消息完整且来源可信
    """
    expected = hmac.new(SECRET_KEY, message, hashlib.sha256).hexdigest()
    # 关键：使用 compare_digest 而非 ==，防止时序攻击
    return hmac.compare_digest(expected, signature)


# --- 使用示例 ---
original_message = b'{"order_id": 12345, "amount": 99.90}'
sig = sign_message(original_message)
print(f"消息: {original_message.decode()}")
print(f"签名: {sig}")

# 正常验证
print(f"验证(未篡改): {verify_message(original_message, sig)}")  # True

# 篡改验证
tampered_message = b'{"order_id": 12345, "amount": 0.01}'
print(f"验证(已篡改): {verify_message(tampered_message, sig)}")  # False

import base64

original_text = "探索 Python 的编码世界！"
original_bytes = original_text.encode('utf-8')

# ========== 编码 ==========
encoded_bytes = base64.b64encode(original_bytes)
encoded_text = encoded_bytes.decode('utf-8')
print(f"原始文本: {original_text}")
print(f"Base64 编码: {encoded_text}")

# ========== 解码 ==========
decoded_bytes = base64.b64decode(encoded_text)
decoded_text = decoded_bytes.decode('utf-8')
print(f"解码还原: {decoded_text}")

import base64

# 包含特殊字符的二进制数据
data = b'\xde\xad\xbe\xef\xfe\xed'

# 标准编码：使用 + 和 /
standard = base64.b64encode(data)
print(f"标准编码:  {standard.decode()}")   # 3q2+7/7t

# URL-Safe 编码：使用 - 和 _
urlsafe = base64.urlsafe_b64encode(data)
print(f"URL-Safe:  {urlsafe.decode()}")    # 3q2-7_7t

# 解码 URL-Safe 字符串（标准解码函数也可处理 URL-Safe 格式）
decoded = base64.urlsafe_b64decode(urlsafe)
print(f"解码还原:  {decoded.hex()}")       # deadbeeffeed

import base64

def image_to_data_url(filepath: str, mime_type: str = "image/png") -> str:
    """
    将图片文件转换为可嵌入 HTML 的 Data URL。

    Args:
        filepath: 图片文件路径
        mime_type: MIME 类型（image/png, image/jpeg, image/gif 等）

    Returns:
        data:image/png;base64,... 格式的 Data URL 字符串
    """
    with open(filepath, "rb") as f:
        encoded = base64.b64encode(f.read()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"

# 使用示例
# data_url = image_to_data_url("logo.png")
# 在 HTML 中: <img src="{data_url}" />