Python文件加密器：基于AES与Fernet实现本地安全传输解决方案

1. 项目概述：为什么我们需要一个“中文安全传输解决方案”？

在数字化办公和日常协作中，我们经常需要通过网络传输一些敏感文件，比如合同草案、财务数据、个人隐私信息，甚至是团队内部尚未公开的创意文档。直接通过微信、QQ或者邮件附件发送，心里总有点不踏实，担心文件在传输过程中被截获，或者不小心发错了人。市面上的商业加密软件要么太笨重，要么需要付费订阅，对于个人或小团队来说，总想找一个轻量、可控、自己能完全理解的方案。这就是我动手写这个“Python文件加密器”的初衷。

它不是一个复杂的密码学套件，而是一个聚焦于“安全传输”这个单一场景的实用工具。核心目标很明确：让用户能用一个自己设定的密码，快速加密一个文件，生成一个密文文件；接收方拿到密文文件和密码后，能快速解密还原出原始文件。整个过程不依赖任何第三方云服务，所有操作都在本地完成，确保数据不出本地，安全可控。特别地，考虑到中文环境用户的使用习惯，工具在提示信息、错误处理和文件命名上都做了优化，避免出现乱码或晦涩的英文术语，这就是“中文安全传输解决方案”的含义——安全、易用、接地气。

这个项目非常适合有一定Python基础，想通过一个完整项目来巩固文件操作、字节流处理、加密库应用的朋友。即使你是新手，跟着步骤一步步来，也能理解其核心原理并成功运行。接下来，我会从设计思路、核心实现、到打包分发和常见问题，完整地拆解这个项目。

2. 核心设计思路与方案选型

2.1 需求拆解与技术栈选择

首先，我们把“文件加密传输”这个需求拆解成几个核心动作：

1. 读取文件：无论什么格式（txt, docx, jpg, zip），都要能当作二进制数据读进来。
2. 加密数据：对二进制数据进行可靠的加密，确保不知道密码的人无法破解。
3. 输出密文：将加密后的数据保存为一个新文件，方便传输。
4. 解密还原：接收方用密码和密文文件，逆向操作得到原始文件。

基于这些动作，技术栈的选择就很清晰了：

• 语言：Python。理由很简单，它语法简洁，拥有强大的标准库和第三方库，特别适合处理文件IO和快速原型开发。hashlib、os、struct这些标准库就能满足我们大部分需求。
• 加密算法：这是核心。我们需要一个对称加密算法，因为加密和解密使用同一个密码。在Python中，cryptography库是当前社区公认的安全、易用的首选。它提供了高级的、难以误用的API。我们将使用cryptography.fernet模块，它基于AES-128-CBC算法，并集成了HMAC签名，能同时保证机密性和完整性（即防止密文被篡改）。
• 用户交互：为了易用性，我们提供命令行界面（CLI）。用户通过输入命令、指定文件路径和密码来操作，这对于自动化脚本和远程服务器操作也非常友好。Python的argparse库可以完美地构建一个清晰的命令行工具。

为什么不直接用zip加密？zip的加密强度历史上曾被质疑，且不同压缩软件的实现可能不一致。自己实现虽然工作量稍大，但算法透明、控制力强，并且是一次宝贵的学习过程。

2.2 项目结构规划

一个清晰的项目结构有助于代码管理和后续扩展。我建议的目录结构如下：

python-file-encryptor/ ├── src/ │ ├── __init__.py │ ├── encryptor.py # 核心加密解密逻辑 │ ├── cli.py # 命令行参数解析与主流程控制 │ └── utils.py # 辅助函数，如文件校验、进度显示 ├── tests/ # 单元测试目录 ├── requirements.txt # 项目依赖列表 ├── setup.py # 打包配置文件 └── README.md # 项目说明文档

我们将核心功能（encryptor.py）与用户界面（cli.py）分离，符合“单一职责原则”。utils.py放置一些通用的工具函数，保持主逻辑的整洁。

3. 核心模块实现详解

3.1 密钥派生与Fernet对象生成

直接使用用户输入的字符串作为加密密钥是不安全的，因为字符串的熵（随机性）可能不足，且长度不一定符合算法要求。标准的做法是使用密钥派生函数（KDF）。我们将使用基于SHA256的HMAC来从用户密码派生出一个固定长度的密钥。

# src/encryptor.py import os from cryptography.fernet import Fernet from cryptography.hazmat.primitives import hashes from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC import base64 def derive_key_from_password(password: str, salt: bytes = None) -> bytes: """ 从用户密码派生出一个安全的密钥。 参数: password: 用户输入的密码字符串。 salt: 盐值。如果为None，则随机生成。盐值不需要保密，但需唯一，用于防止彩虹表攻击。 返回: 派生出的密钥（bytes）。 """ # 将密码编码为字节 password_bytes = password.encode('utf-8') # 如果未提供盐值，则生成一个随机盐值（16字节是常用长度） if salt is None: salt = os.urandom(16) # 使用PBKDF2HMAC进行密钥派生。迭代次数设为100000以增加暴力破解成本。 kdf = PBKDF2HMAC( algorithm=hashes.SHA256(), length=32, # 派生密钥长度 salt=salt, iterations=100000, ) key = base64.urlsafe_b64encode(kdf.derive(password_bytes)) return key, salt # 返回密钥和盐值，盐值需要和密文一起保存

注意：盐值（salt）必须随机生成且唯一。它的作用是确保即使用户密码相同，每次加密生成的密钥也不同，从而有效防御针对常用密码的“彩虹表”攻击。盐值不需要保密，可以明文和密文一起存储，我们后续会将其嵌入到密文文件中。

得到派生密钥后，就可以创建Fernet对象了：

def create_fernet_cipher(key: bytes) -> Fernet: """根据派生出的密钥创建Fernet加密/解密器。""" return Fernet(key)

3.2 文件加密流程与数据封装

加密不仅仅是调用encrypt()。我们需要设计一个文件格式，将加密后的数据、盐值以及其他可能的元数据（如原始文件名）打包在一起，形成一个完整的“.enc”密文文件。这样接收方拿到一个文件就能解密，无需额外信息（除了密码）。

我设计的密文文件结构如下：

[文件头标识（4字节）][盐值长度（2字节）][盐值（变长）][密文数据（变长）]

• 文件头标识：例如b'ENCF'，用于快速识别这是一个由本工具生成的密文文件。
• 盐值长度：用2个字节的无符号短整数存储，表示后面盐值的实际长度。
• 盐值：派生密钥时使用的随机盐。
• 密文数据：由Fernet.encrypt()生成的完整密文（包含了加密的原始文件数据和Fernet自带的HMAC验证信息）。

def encrypt_file(input_file_path: str, password: str, output_file_path: str = None) -> str: """ 加密文件。 参数: input_file_path: 待加密文件的路径。 password: 加密密码。 output_file_path: 输出密文文件路径。如果为None，则在原文件名后加“.enc”。 返回: 生成的密文文件路径。 """ if not os.path.exists(input_file_path): raise FileNotFoundError(f"输入文件不存在: {input_file_path}") # 1. 读取原始文件数据 with open(input_file_path, 'rb') as f: plaintext_data = f.read() # 2. 派生密钥（生成随机盐） key, salt = derive_key_from_password(password) cipher = create_fernet_cipher(key) # 3. 加密数据 encrypted_data = cipher.encrypt(plaintext_data) # 4. 构建最终密文文件字节流 header = b'ENCF' # 自定义文件头 salt_len = len(salt) # 使用struct模块将盐值长度打包为2字节的无符号短整数（网络字节序，大端） import struct salt_len_bytes = struct.pack('>H', salt_len) final_ciphertext = header + salt_len_bytes + salt + encrypted_data # 5. 确定输出路径并写入文件 if output_file_path is None: output_file_path = input_file_path + '.enc' with open(output_file_path, 'wb') as f: f.write(final_ciphertext) print(f"[成功] 文件已加密: {input_file_path} -> {output_file_path}") return output_file_path

3.3 文件解密流程与完整性校验

解密是加密的逆过程，但需要更严谨的错误处理，因为输入的密文文件可能被损坏、篡改，或者密码错误。

def decrypt_file(input_file_path: str, password: str, output_file_path: str = None) -> str: """ 解密文件。 参数: input_file_path: 密文文件路径（.enc文件）。 password: 解密密码。 output_file_path: 输出原始文件路径。如果为None，则尝试去除“.enc”后缀。 返回: 解密后的文件路径。 """ if not os.path.exists(input_file_path): raise FileNotFoundError(f"输入文件不存在: {input_file_path}") with open(input_file_path, 'rb') as f: file_data = f.read() # 1. 解析文件头 if len(file_data) < 6 or file_data[:4] != b'ENCF': # 至少要有头4字节+盐长2字节 raise ValueError("无效的密文文件格式或文件头损坏。") # 2. 提取盐值长度和盐值 salt_len = struct.unpack('>H', file_data[4:6])[0] # 解包盐值长度 if 6 + salt_len > len(file_data): raise ValueError("密文文件长度异常，可能已损坏。") salt = file_data[6:6 + salt_len] encrypted_data = file_data[6 + salt_len:] # 3. 使用相同的密码和提取的盐值派生密钥 key, _ = derive_key_from_password(password, salt=salt) cipher = create_fernet_cipher(key) # 4. 解密数据 (Fernet.decrypt()会同时验证HMAC，如果密文被篡改或密码错误，会抛出异常) try: plaintext_data = cipher.decrypt(encrypted_data) except Exception as e: # 这里可能会捕获到InvalidToken等异常 # 提供更友好的中文错误提示 if "Invalid token" in str(e) or "Signature did not match" in str(e): raise ValueError("解密失败！可能原因：1) 密码错误；2) 密文文件被篡改。") from e else: raise # 5. 确定输出路径并写入文件 if output_file_path is None: if input_file_path.endswith('.enc'): output_file_path = input_file_path[:-4] # 去掉.enc后缀 else: output_file_path = input_file_path + '.decrypted' with open(output_file_path, 'wb') as f: f.write(plaintext_data) print(f"[成功] 文件已解密: {input_file_path} -> {output_file_path}") return output_file_path

实操心得：Fernet.decrypt()方法在密码错误或密文被篡改时会抛出cryptography.fernet.InvalidToken异常。我们在捕获异常后，将其转换为更明确的中文提示，极大提升了用户体验。这是编写友好CLI工具的一个重要细节。

4. 构建命令行界面（CLI）

有了核心的加密解密函数，我们需要一个方便用户调用的入口。使用argparse库可以轻松构建。

# src/cli.py import argparse import sys import os sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from src.encryptor import encrypt_file, decrypt_file def main(): parser = argparse.ArgumentParser( description='Python文件加密器 - 安全的中文文件传输解决方案', epilog='示例：\n' ' 加密: python -m src.cli encrypt secret.docx -p mypassword\n' ' 解密: python -m src.cli decrypt secret.docx.enc -p mypassword', formatter_class=argparse.RawDescriptionHelpFormatter ) subparsers = parser.add_subparsers(dest='command', help='子命令', required=True) # 加密子命令 encrypt_parser = subparsers.add_parser('encrypt', help='加密一个文件') encrypt_parser.add_argument('input', help='待加密的文件路径') encrypt_parser.add_argument('-o', '--output', help='输出密文文件路径（可选）') encrypt_parser.add_argument('-p', '--password', required=True, help='加密密码') # 解密子命令 decrypt_parser = subparsers.add_parser('decrypt', help='解密一个文件') decrypt_parser.add_argument('input', help='待解密的密文文件路径（.enc文件）') decrypt_parser.add_argument('-o', '--output', help='输出原始文件路径（可选）') decrypt_parser.add_argument('-p', '--password', required=True, help='解密密码') args = parser.parse_args() try: if args.command == 'encrypt': encrypt_file(args.input, args.password, args.output) elif args.command == 'decrypt': decrypt_file(args.input, args.password, args.output) else: parser.print_help() except FileNotFoundError as e: print(f"[错误] 文件未找到: {e}", file=sys.stderr) sys.exit(1) except ValueError as e: print(f"[错误] {e}", file=sys.stderr) sys.exit(1) except Exception as e: print(f"[未知错误] 操作失败: {e}", file=sys.stderr) sys.exit(1) if __name__ == '__main__': main()

这样，用户就可以在命令行中像使用系统命令一样操作了：

# 加密 python -m src.cli encrypt 重要报告.pdf -p 我的强密码123 -o 报告.enc # 解密 python -m src.cli decrypt 报告.enc -p 我的强密码123 -o 重要报告_解密.pdf

5. 项目封装与分发

为了让工具更容易安装和使用，我们需要将其打包。创建setup.py文件。

# setup.py from setuptools import setup, find_packages with open("README.md", "r", encoding="utf-8") as fh: long_description = fh.read() setup( name="pyfile-encryptor", version="1.0.0", author="Your Name", author_email="your.email@example.com", description="一个用于安全文件传输的Python命令行加密工具", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/yourusername/python-file-encryptor", packages=find_packages(where="."), package_dir={"": "."}, classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ], python_requires=">=3.7", install_requires=[ "cryptography>=3.4", # 核心加密库 ], entry_points={ "console_scripts": [ "file-encryptor=src.cli:main", # 创建全局命令 `file-encryptor` ], }, )

同时，创建requirements.txt文件，列出核心依赖：

cryptography>=3.4

现在，你可以使用以下命令进行开发和安装：

1. 安装依赖：pip install -r requirements.txt
2. 以开发模式安装包：pip install -e .这样，你在源码中的修改会立刻反映到安装的命令中。
3. 直接使用命令：安装后，可以直接在终端使用file-encryptor encrypt ...命令。

如果你想分享给他人，可以构建分发包：

# 构建源码包和wheel包 python setup.py sdist bdist_wheel # 使用twine上传到PyPI（需要先配置） # twine upload dist/*

6. 进阶功能与安全考量

6.1 增加进度显示与大型文件支持

加密大文件时，用户可能需要等待。我们可以添加一个简单的进度条。这里使用tqdm库，它是一个非常流行的进度条工具。首先将其加入requirements.txt，然后修改加密解密函数。

# 在encryptor.py中修改 from tqdm import tqdm def encrypt_file_large(input_path, password, output_path=None, chunk_size=64*1024): """支持大文件分块加密，并显示进度。""" # ... 前面的盐值生成、密钥派生与加密器创建代码不变 ... cipher = create_fernet_cipher(key) # 获取输入文件大小用于进度条 total_size = os.path.getsize(input_path) if output_path is None: output_path = input_path + '.enc' with open(input_path, 'rb') as fin, open(output_path, 'wb') as fout: # 先写入文件头和盐值 header = b'ENCF' salt_len_bytes = struct.pack('>H', len(salt)) fout.write(header + salt_len_bytes + salt) # 分块读取、加密、写入，并显示进度 with tqdm(total=total_size, unit='B', unit_scale=True, desc="加密中") as pbar: while True: chunk = fin.read(chunk_size) if not chunk: break encrypted_chunk = cipher.encrypt(chunk) # 注意：Fernet加密后数据会膨胀，需要原样写入。 fout.write(encrypted_chunk) pbar.update(len(chunk)) print(f"[成功] 文件已加密: {input_path} -> {output_path}") return output_path

注意：Fernet加密模式（AES-CBC）要求数据按块处理，且加密后数据长度会增加（由于填充和HMAC）。对于大文件，更高效的做法是使用cryptography库底层的AES算法结合CBC或GCM模式，并自行处理分块。但为了代码简洁和安全性（HMAC验证），本例仍使用Fernet，它内部会处理数据。对于超大文件（>数GB），需注意内存和性能，上述分块读取主要是为了进度显示，实际加密仍在内存中进行。生产环境应考虑使用cryptography.hazmat.primitives.ciphers进行真正的流式加密。

6.2 密码强度检查与交互式输入

强制用户使用强密码是个好习惯。我们可以添加一个简单的密码强度检查函数，并在CLI中提供交互式密码输入（隐藏回显）。

# src/utils.py import re import getpass # 用于隐藏密码输入 def check_password_strength(password): """检查密码强度。返回(是否通过, 提示信息)。""" if len(password) < 8: return False, "密码长度至少8位。" if not re.search(r"[a-z]", password): return False, "密码应包含至少一个小写字母。" if not re.search(r"[A-Z]", password): return False, "密码应包含至少一个大写字母。" if not re.search(r"\d", password): return False, "密码应包含至少一个数字。" # 可选：检查特殊字符 # if not re.search(r"[!@#$%^&*(),.?\":{}|<>]", password): # return False, "密码应包含至少一个特殊字符。" return True, "密码强度足够。" def get_password_from_user(prompt="请输入密码: ", confirm=True): """安全地从用户获取密码（不显示）。""" while True: password = getpass.getpass(prompt) if not password: print("密码不能为空。") continue is_strong, msg = check_password_strength(password) if not is_strong: print(f"密码强度不足: {msg}") if input("仍要使用此密码吗？(y/N): ").lower() != 'y': continue if confirm: password2 = getpass.getpass("请再次输入密码以确认: ") if password != password2: print("两次输入的密码不一致，请重新输入。") continue return password

然后在cli.py中，可以修改参数逻辑，让-p参数变为可选，如果未提供则调用交互式输入。

6.3 安全警告与最佳实践

1. 密码是关键：本工具的安全性完全依赖于用户密码的强度。务必使用强密码，并妥善保管。密码一旦丢失，文件将无法恢复。
2. 密文文件保管：.enc文件包含了加密数据和盐值。虽然单独拿到它无法解密，但应和密码分开传输和存储。例如，通过不同渠道发送密码和文件。
3. 算法与迭代次数：我们使用的是目前公认安全的AES-128和PBKDF2-HMAC-SHA256。迭代次数（100000）可以在derive_key_from_password函数中调整，增加迭代次数能提高暴力破解成本，但也会略微增加加密解密时间。
4. 环境安全：确保运行此脚本的计算机环境是安全的，没有恶意软件记录你的键盘输入或截屏。

7. 常见问题与排查技巧实录

在实际使用和教学过程中，我遇到了不少典型问题。这里列出一个速查表，方便你快速定位。

一个典型的调试案例：用户反馈解密失败，提示“无效的密文文件格式”。首先，我让他用十六进制查看器（如xxd命令或VSCode的Hex Editor插件）查看文件开头几个字节。他反馈说开头是50 4B 03 04，这是ZIP文件的魔数（PK..）。原来他误将一个普通的zip文件当作.enc文件来解密了。这个案例说明，文件格式验证非常必要，也能快速帮用户定位问题根源。

最后，这个项目的代码我已经放在了GitHub上，包含了文中提到的所有基础功能和部分进阶功能。你可以克隆下来，边运行边学习，并根据自己的需求进行修改和扩展。比如，增加图形界面（用Tkinter或PyQt）、支持文件夹递归加密、集成到右键菜单等。安全工具的构建，理解其原理远比会用更重要，希望这个详细的拆解能帮你打下坚实的基础。