加密解密 (crypto)

本模块提供了安全的字符串加密和解密功能，支持多种加密策略和自定义密码保护。该模块采用了先进的代码混淆技术，确保加密算法的实现细节得到有效保护。

特性

  • 双重加密策略: 优先使用 Fernet 对称加密（基于 AES 128），当 cryptography 库不可用时自动回退到 XOR 加密

  • 自定义密码支持: 支持用户自定义密码，也可使用内置的默认密钥

  • Unicode 支持: 完美处理中文等多字节字符

  • 代码混淆保护: 核心算法通过 base64 编码和动态函数生成技术进行混淆

  • 错误处理: 完整的异常处理机制和用户友好的错误信息

  • 零依赖回退: 即使没有额外依赖也能正常工作

安装

使用基本功能（XOR 加密）:

pip install pywayne

使用高级功能（Fernet 加密）:

pip install pywayne[crypto]

快速开始

基本用法

from pywayne.crypto import encrypt, decrypt

# 使用默认密钥加密
encrypted = encrypt("Hello World")
decrypted = decrypt(encrypted)
print(decrypted)  # 输出: Hello World

自定义密码加密

from pywayne.crypto import encrypt, decrypt

# 使用自定义密码
password = "my_secret_password"
encrypted = encrypt("机密信息", password)
decrypted = decrypt(encrypted, password)
print(decrypted)  # 输出: 机密信息

处理不同数据类型

from pywayne.crypto import encrypt, decrypt

# 字符串加密
text_encrypted = encrypt("文本信息", "password123")

# 字节数据加密
byte_data = b"binary data"
byte_encrypted = encrypt(byte_data, "password123")

# 解密
text_decrypted = decrypt(text_encrypted, "password123")
byte_decrypted = decrypt(byte_encrypted, "password123")

API 参考

encrypt 函数

encrypt(text: str | bytes, password: str = None) → str

加密字符串或字节数据。

参数:

  • text (str or bytes): 要加密的文本数据

  • password (str, 可选): 自定义密码。如果不提供，则使用默认密钥

返回值:

  • str: 加密后的 base64 编码字符串

异常:

  • ValueError: 当输入参数类型无效时抛出

示例:

# 基本用法
encrypted = encrypt("Hello World")

# 使用密码
encrypted = encrypt("Secret message", "my_password")

# 处理字节数据
encrypted = encrypt(b"binary data", "password")

decrypt 函数

decrypt(encrypted_text: str, password: str = None) → str

解密字符串。

参数:

  • encrypted_text (str): 要解密的 base64 编码字符串

  • password (str, 可选): 解密密码。必须与加密时使用的密码相同

返回值:

  • str: 解密后的原始字符串

异常:

  • ValueError: 当解密失败时抛出（数据损坏或密码错误）

示例:

# 基本用法
original = decrypt(encrypted_text)

# 使用密码解密
original = decrypt(encrypted_text, "my_password")

错误处理

常见错误类型

from pywayne.crypto import encrypt, decrypt

try:
    # 错误的数据类型
    encrypt(123)
except ValueError as e:
    print("错误: 输入类型必须是字符串或字节")

try:
    # 错误的密码
    decrypt(encrypted_text, "wrong_password")
except ValueError as e:
    print("错误: 解密失败，密码不正确")

try:
    # 损坏的数据
    decrypt("invalid_base64_data")
except ValueError as e:
    print("错误: 数据格式无效")

最佳实践

密码安全

import os
from pywayne.crypto import encrypt, decrypt

# 使用环境变量存储密码
password = os.getenv('ENCRYPTION_PASSWORD', 'default_password')

# 加密敏感数据
sensitive_data = "用户的隐私信息"
encrypted = encrypt(sensitive_data, password)

# 安全解密
try:
    decrypted = decrypt(encrypted, password)
    print(f"解密成功: {decrypted}")
except ValueError:
    print("解密失败: 密码错误或数据损坏")

批量处理

from pywayne.crypto import encrypt, decrypt

def encrypt_batch(data_list, password):
    """批量加密数据"""
    return [encrypt(item, password) for item in data_list]

def decrypt_batch(encrypted_list, password):
    """批量解密数据"""
    results = []
    for item in encrypted_list:
        try:
            results.append(decrypt(item, password))
        except ValueError:
            results.append(None)  # 解密失败的项目
    return results

# 使用示例
data = ["数据1", "数据2", "数据3"]
password = "batch_password"

encrypted = encrypt_batch(data, password)
decrypted = decrypt_batch(encrypted, password)

技术细节

加密算法

本模块采用分层加密策略：

  1. Fernet 加密 (推荐)

    • 基于 AES 128 对称加密

    • 包含消息完整性验证

    • 使用 SHA256 进行密钥派生

    • 需要 cryptography 库支持

  2. XOR 加密 (回退方案)

    • 简单的异或加密算法

    • 无需额外依赖

    • 适用于基本的数据混淆

代码混淆

为了保护加密算法的实现细节，本模块采用了多种混淆技术：

  • Base64 编码隐藏: 核心算法代码通过 base64 编码存储

  • 动态函数生成: 运行时动态创建函数，避免静态分析

  • 命名空间清理: 执行后立即删除敏感变量

  • 分散式架构: 将核心逻辑分散到多个独立的编码块

注意事项

安全提醒

  • 本模块主要用于数据混淆和基本加密保护

  • 对于高安全性要求的应用，建议使用专业的加密库

  • 密码应当妥善保管，避免硬编码在源码中

  • 定期更新 cryptography 库以获得最新的安全特性

性能考虑

  • Fernet 加密的性能优于 XOR 加密的安全性

  • 对于大量数据的加密，建议分块处理

  • 密钥派生过程会消耗一定的计算资源

兼容性

  • 支持 Python 3.6+

  • 跨平台兼容（Windows、macOS、Linux）

  • 与其他 pywayne 模块完全兼容

示例应用

配置文件加密

import json
from pywayne.crypto import encrypt, decrypt

def save_config(config_dict, password, filename):
    """保存加密的配置文件"""
    config_json = json.dumps(config_dict, ensure_ascii=False)
    encrypted_config = encrypt(config_json, password)

    with open(filename, 'w') as f:
        f.write(encrypted_config)

def load_config(password, filename):
    """加载并解密配置文件"""
    with open(filename, 'r') as f:
        encrypted_config = f.read()

    try:
        config_json = decrypt(encrypted_config, password)
        return json.loads(config_json)
    except ValueError:
        raise ValueError("配置文件解密失败，请检查密码")

# 使用示例
config = {
    "database": {
        "host": "localhost",
        "username": "admin",
        "password": "secret123"
    }
}

save_config(config, "master_password", "config.enc")
loaded_config = load_config("master_password", "config.enc")

日志加密

import logging
from pywayne.crypto import encrypt

class EncryptedFileHandler(logging.FileHandler):
    """加密的日志文件处理器"""

    def __init__(self, filename, password, mode='a', encoding=None):
        self.password = password
        super().__init__(filename, mode, encoding)

    def emit(self, record):
        """加密日志记录后写入文件"""
        try:
            msg = self.format(record)
            encrypted_msg = encrypt(msg, self.password)

            # 写入加密的日志
            with open(self.baseFilename, 'a', encoding='utf-8') as f:
                f.write(encrypted_msg + '\n')
        except Exception:
            self.handleError(record)

# 使用示例
logger = logging.getLogger('encrypted_logger')
handler = EncryptedFileHandler('app.log.enc', 'log_password')
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

logger.info("这条日志将被加密存储")