当前位置：首页 > news >正文

Python cryptography库实战：使用AES-GCM加密保护TXT文件安全

news 2026/7/5 10:04:37

1. 项目概述：为什么选择 cryptography 库来加密你的 txt 文件？

在日常开发或者个人数据管理中，我们总会遇到一些敏感信息需要处理，比如配置文件里的数据库密码、日志里的用户手机号，或者就是一份不想让别人轻易看到的私人笔记。直接把这些信息以明文形式存放在 txt 文件里，就像把家门钥匙放在门垫下面，安全感几乎为零。这时候，给文本文件“上把锁”就成了刚需。

市面上加密工具很多，有在线网站，也有各种桌面软件，但它们要么有泄露风险，要么不够灵活，无法集成到自动化流程里。作为一名开发者，我们更倾向于一种可编程、可控制、高安全性的方案。Python 的cryptography库正是为此而生。它不是一个简单的“加密函数”集合，而是一个由密码学专家维护的、生产级别的工具包，底层通常链接到 OpenSSL 这样的成熟密码学库，确保了算法的正确性和高效性。相比于自己手写 AES、RSA 算法（极易出错且不安全），或者使用一些已过时、存在漏洞的库（如早期的pycrypto），cryptography提供了“安全默认值”，引导开发者走向正确的实践。

所以，这个项目的核心就是：利用cryptography库，实现一个既安全又易于集成的命令行工具（或函数模块），用于对任意 txt 文本文件进行可靠的加密与解密。它适合任何需要程序化处理文本加密的 Python 开发者，无论是运维工程师加密脚本中的密钥，还是后端开发保护本地缓存数据，都能直接“抄作业”。

2. 核心思路与方案选型：对称加密为何是 txt 文件的“首选”？

面对加密，第一个要做的选择题就是：用对称加密还是非对称加密？

非对称加密（如 RSA）：公钥加密，私钥解密。安全性高，常用于密钥交换或数字签名。但它计算慢，且加密后的数据体积会膨胀（对明文长度有限制），不适合直接加密可能较大的文本文件。
对称加密（如 AES）：加密和解密使用同一把密钥。速度快，效率高，适合加密大量数据，比如我们的文本文件。

显然，对称加密是加密文件内容的最佳拍档。在cryptography库中，对称加密的“明星算法”就是AES（Advanced Encryption Standard），并结合合适的操作模式，如GCM（Galois/Counter Mode）。

这里重点解释一下为什么选 AES-GCM，而不是更早的 CBC 模式：

认证加密：GCM 模式不仅提供保密性（别人看不懂），还提供完整性认证（数据没被篡改）。它在加密的同时会生成一个“认证标签”（Tag），解密时会先验证这个标签，如果文件在存储过程中被恶意修改了一个字节，解密会直接失败报错，而不是输出一堆乱码。这比 CBC 模式安全得多。
无需填充：AES 是块加密算法，需要将数据分割成固定大小的块（如128位）。CBC 模式需要“填充”最后一个不完整的块，填充规则若处理不当可能带来漏洞（如 Padding Oracle 攻击）。而 GCM 模式本质上是流加密模式，完美避开了填充问题。
附带关联数据：GCM 支持认证“关联数据”，这部分数据不加密但参与认证。我们可以把文件名、版本号等元数据放进去，确保加密文件和解密上下文绑定。

因此，我们的技术栈非常明确：Python + cryptography 库 + AES-GCM 算法。密钥我们将通过一个安全的随机数生成器来创建，并妥善保存。

注意：任何加密方案的安全性都严重依赖于密钥的保密性。本方案会生成一个强随机密钥，你必须像保护银行卡密码一样保护它。丢失密钥意味着数据永久丢失，泄露密钥则意味着加密形同虚设。

3. 环境准备与 cryptography 库安装要点

工欲善其事，必先利其器。首先确保你有一个可用的 Python 环境（3.6 及以上版本推荐）。然后，我们通过 pip 安装cryptography。

pip install cryptography

这个命令看起来简单，但背后有几个坑需要提前知晓：

编译依赖：cryptography底层依赖 C 扩展（为了性能和安全），在 Windows 上通常直接提供预编译的轮子（wheel），安装很顺利。但在 Linux 或 macOS 上，如果系统缺少必要的编译工具链（如gcc,libffi,openssl开发头文件），安装可能会失败并报出一堆红色错误。对于 Linux（如 Ubuntu/Debian），你可以先运行sudo apt-get install build-essential libssl-dev libffi-dev python3-dev来安装依赖。
版本选择：尽量使用最新稳定版。新版本会修复已知的安全漏洞。你可以用pip install cryptography --upgrade来升级。
虚拟环境：强烈建议在虚拟环境（如venv,conda）中操作。这样可以避免污染系统级的 Python 环境，也便于管理项目依赖。创建虚拟环境的命令是python -m venv my_crypto_env，然后激活它。

安装成功后，可以在 Python 交互环境中快速验证一下：

import cryptography print(cryptography.__version__)

如果能正常输出版本号，说明库已就绪。

4. 实战：分步实现 txt 文件的加密与解密

接下来，我们将把理论转化为代码。我会将整个过程拆解成几个函数，并附上详尽的注释和解释。

4.1 密钥的生成与管理：安全的第一道门

密钥是加密体系的基石。我们使用cryptography.hazmat.primitives中的ciphers模块和kdf（密钥派生函数）模块来生成一个适合 AES-256 的密钥（256位，即32字节）。

import os from cryptography.hazmat.primitives.ciphers import algorithms from cryptography.hazmat.primitives.kdf.scrypt import Scrypt def generate_and_save_key(key_file_path='secret.key', salt=None): """ 生成一个安全的 AES-256 密钥并保存到文件。 参数: key_file_path: 保存密钥的文件路径。 salt: 用于密钥派生的盐值。如果为None，则生成随机盐。 返回: key: 生成的密钥（bytes）。 salt: 使用的盐值（bytes），需要和密钥一起保存。 """ # 1. 生成或使用提供的盐。盐是公开的，用于防止彩虹表攻击，确保每次用相同密码派生出的密钥不同。 if salt is None: salt = os.urandom(16) # 生成16字节的随机盐 # 2. 使用 Scrypt 密钥派生函数。这里我们没有用户密码，所以用一个固定的、足够长的“密码”。 # 实际上，更好的做法是让用户输入口令，然后用口令派生密钥。这里为简化，我们生成随机密钥材料。 # 生成一个随机的“主密钥材料”。 master_key_material = os.urandom(32) # 3. 使用 Scrypt 对主密钥材料进行“拉伸”和混淆，增加暴力破解难度。 kdf = Scrypt( salt=salt, length=32, # 我们希望派生出一个32字节（256位）的密钥 n=2**14, # CPU/内存成本参数。值越大越安全，但计算越慢。 r=8, # 块大小参数。 p=1, # 并行化参数。 ) key = kdf.derive(master_key_material) # 派生最终密钥 # 4. 将密钥和盐保存到文件。注意：这个文件本身必须严格保密！ with open(key_file_path, 'wb') as key_file: key_file.write(salt + key) # 通常将盐和密钥拼接存储 print(f"[*] 密钥已生成并保存至: {key_file_path}") print(f"[!] 警告：请务必妥善保管 '{key_file_path}' 文件！丢失它将无法解密任何数据！") return key, salt

关键点解析：

为什么用 Scrypt？我们这里模拟了一个场景：即使攻击者拿到了存储的密钥文件（salt+key），由于 Scrypt 的计算密集型特性，他也无法反向推导出原始的master_key_material。如果我们采用用户口令，Scrypt 能有效抵御针对弱口令的暴力破解和彩虹表攻击。
盐（Salt）的作用：盐是一个随机值，与密钥材料一起输入 KDF。它的存在确保了即使两个用户使用了相同的密码，最终生成的密钥也不同，也防止了攻击者使用预计算的彩虹表进行批量破解。
密钥保存：我们将盐和派生后的密钥拼接保存在一个文件里。在实际应用中，这个.key文件的安全等级应该是最高的。可以考虑将其放在只有特定用户有权限读取的目录，或者使用硬件安全模块（HSM）等更专业的方式管理。

4.2 加密函数实现：为文本穿上“盔甲”

有了密钥，我们就可以加密了。加密函数需要读取明文文件，使用 AES-GCM 进行加密，并将密文、Nonce（一次性随机数）和认证标签（Tag）一起写入新文件。

from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes def encrypt_file(input_file_path, output_file_path, key): """ 使用 AES-GCM 模式加密一个文本文件。 参数: input_file_path: 待加密的明文文件路径。 output_file_path: 加密后的输出文件路径。 key: 用于加密的密钥（bytes，长度需符合算法要求，如AES-256为32字节）。 """ # 1. 读取明文内容 with open(input_file_path, 'rb') as file: plaintext = file.read() # 2. 生成一个随机的 Nonce（对于 GCM 模式，通常推荐 12 字节） # Nonce 是“一次性数字”，确保同样的明文和密钥每次加密结果都不同，防止重放攻击。 nonce = os.urandom(12) # 3. 构建 AES-GCM 密码器并加密 # 在 GCM 模式下，我们不需要手动指定初始化向量（IV），Nonce 扮演了类似角色。 algorithm = algorithms.AES(key) cipher = Cipher(algorithm, mode=modes.GCM(nonce)) encryptor = cipher.encryptor() # 如果有关联数据（AAD），可以在这里添加。例如文件头信息。 # encryptor.authenticate_additional_data(aad) ciphertext = encryptor.update(plaintext) + encryptor.finalize() # 4. 获取认证标签（Tag） tag = encryptor.tag # 5. 将 Nonce、Tag 和密文一起写入输出文件 # 存储顺序可以是：Nonce + Tag + Ciphertext。解密时需要知道这个顺序。 with open(output_file_path, 'wb') as file: file.write(nonce) file.write(tag) file.write(ciphertext) print(f"[+] 加密完成。密文文件: {output_file_path}") print(f" Nonce 长度: {len(nonce)} 字节, Tag 长度: {len(tag)} 字节")

实操心得：

Nonce 的管理：Nonce 绝对不可以重复使用！用相同的（Key, Nonce）对加密两条不同的信息，会严重破坏 GCM 模式的安全性，可能导致密钥泄露。os.urandom(12)在密码学上是安全的随机源，可以信任。
文件格式：我们将 Nonce、Tag 和 Ciphertext 直接拼接存储。这是一种简单有效的方式。你也可以设计一个更结构化的文件头，比如包含版本号、算法标识、数据长度等，让程序更具扩展性和健壮性。
大文件处理：上面的代码一次性将整个文件读入内存。如果加密几个G的大文件，这会很吃内存。cryptography的encryptor.update()支持流式处理，你可以分块读取文件、分块加密、分块写入，内存中只保留一小块数据。

4.3 解密函数实现：验证并还原真相

解密是加密的逆过程，但多了一个关键步骤：验证认证标签（Tag）。

def decrypt_file(input_file_path, output_file_path, key): """ 使用 AES-GCM 模式解密一个文件。 参数: input_file_path: 待解密的密文文件路径。 output_file_path: 解密后的明文输出文件路径。 key: 用于解密的密钥（必须与加密密钥相同）。 异常: cryptography.exceptions.InvalidTag: 如果认证失败（文件被篡改或密钥错误）。 """ # 1. 读取密文文件 with open(input_file_path, 'rb') as file: data = file.read() # 2. 按照加密时约定的格式解析数据 # 我们约定前12字节是 Nonce，接着16字节是 Tag，剩下的是 Ciphertext nonce = data[:12] tag = data[12:28] # GCM 模式默认 Tag 长度为 16 字节（128位） ciphertext = data[28:] # 3. 构建 AES-GCM 解密器 algorithm = algorithms.AES(key) cipher = Cipher(algorithm, mode=modes.GCM(nonce, tag)) decryptor = cipher.decryptor() # 如果加密时添加了关联数据（AAD），解密时必须提供完全相同的数据进行验证。 # decryptor.authenticate_additional_data(aad) # 4. 解密并验证 Tag。如果验证失败，`finalize()` 会抛出 `InvalidTag` 异常。 try: plaintext = decryptor.update(ciphertext) + decryptor.finalize() except Exception as e: # 更精确地捕获 InvalidTag 异常 from cryptography.exceptions import InvalidTag if isinstance(e, InvalidTag): print(f"[!] 解密失败：认证标签无效。文件可能已被篡改，或使用了错误的密钥。") raise else: raise # 5. 将明文写入输出文件 with open(output_file_path, 'wb') as file: file.write(plaintext) print(f"[+] 解密成功！明文文件: {output_file_path}")

核心安全机制：decryptor.finalize()这一步至关重要。它内部会验证 Tag。只有 Tag 验证通过，它才会返回并允许你获取明文。如果文件在存储过程中被修改（哪怕只改了一个比特），或者你使用了错误的密钥，Tag 验证都会失败，程序会抛出InvalidTag异常。这保证了数据的完整性和真实性。在捕获异常时，明确区分是认证失败还是其他错误，能给用户更清晰的提示。

4.4 整合与命令行界面：打造易用的工具

将上述函数整合起来，并添加一个简单的命令行界面，让工具用起来更方便。我们可以使用 Python 内置的argparse库。

import argparse def main(): parser = argparse.ArgumentParser(description='使用 AES-GCM 加密/解密 TXT 文本文件。') subparsers = parser.add_subparsers(dest='command', help='子命令', required=True) # 生成密钥子命令 gen_parser = subparsers.add_parser('genkey', help='生成一个新的加密密钥并保存到文件') gen_parser.add_argument('-o', '--output', default='secret.key', help='密钥输出文件路径 (默认: secret.key)') # 加密子命令 enc_parser = subparsers.add_parser('encrypt', help='加密一个文件') enc_parser.add_argument('-i', '--input', required=True, help='待加密的输入文件路径') enc_parser.add_argument('-o', '--output', required=True, help='加密后的输出文件路径') enc_parser.add_argument('-k', '--keyfile', default='secret.key', help='密钥文件路径 (默认: secret.key)') # 解密密子命令 dec_parser = subparsers.add_parser('decrypt', help='解密一个文件') dec_parser.add_argument('-i', '--input', required=True, help='待解密的输入文件路径') dec_parser.add_argument('-o', '--output', required=True, help='解密后的输出文件路径') dec_parser.add_argument('-k', '--keyfile', default='secret.key', help='密钥文件路径 (默认: secret.key)') args = parser.parse_args() if args.command == 'genkey': generate_and_save_key(args.output) elif args.command == 'encrypt': # 从密钥文件读取盐和密钥 with open(args.keyfile, 'rb') as f: data = f.read() salt = data[:16] stored_key = data[16:] # 假设之前保存的是 salt(16)+key(32) # 注意：这里直接读取了存储的派生密钥。更严谨的做法是重新用盐和主密钥材料派生一次以验证。 # 为简化，我们假设存储的就是可直接使用的密钥。 key = stored_key if len(key) != 32: print(f"[!] 错误：密钥文件 '{args.keyfile}' 中的密钥长度无效。应为32字节。") return encrypt_file(args.input, args.output, key) elif args.command == 'decrypt': with open(args.keyfile, 'rb') as f: data = f.read() stored_key = data[16:] # 跳过盐，读取密钥 key = stored_key if len(key) != 32: print(f"[!] 错误：密钥文件 '{args.keyfile}' 中的密钥长度无效。应为32字节。") return decrypt_file(args.input, args.output, key) if __name__ == '__main__': main()

现在，你可以将整个脚本保存为txt_crypto_tool.py，然后在命令行中像这样使用它：

# 1. 生成密钥（首次使用） python txt_crypto_tool.py genkey -o my_secret.key # 2. 加密一个文件 python txt_crypto_tool.py encrypt -i sensitive.txt -o sensitive.txt.enc -k my_secret.key # 3. 解密该文件 python txt_crypto_tool.py decrypt -i sensitive.txt.enc -o sensitive_decrypted.txt -k my_secret.key

5. 进阶探讨与安全强化建议

基础功能实现后，我们可以思考如何让它更健壮、更安全。

5.1 密钥管理：从文件到口令

上面我们把密钥保存在文件里，这要求文件系统本身是安全的。另一种更常见、对用户更友好的方式是使用口令（Password）派生密钥。用户只需记住一个口令，程序通过口令和盐（Salt）动态生成密钥。这样，密钥本身不存储，安全性转移到了口令的强度上。

from cryptography.hazmat.primitives.kdf.scrypt import Scrypt import getpass # 用于安全输入口令 def derive_key_from_password(password: bytes, salt: bytes) -> bytes: """使用 Scrypt 从口令和盐派生密钥。""" kdf = Scrypt(salt=salt, length=32, n=2**14, r=8, p=1) key = kdf.derive(password) return key # 在加密/解密时 password = getpass.getpass("请输入加密口令: ").encode('utf-8') # 盐需要和加密文件一起存储（可以放在文件头） salt = os.urandom(16) key = derive_key_from_password(password, salt) # 然后将 salt 和 ciphertext, tag, nonce 一起存储

注意事项：口令的强度直接决定安全性。务必引导用户设置强口令（长、混合字符）。Scrypt 的参数（n, r, p）可以调整来增加派生难度，抵御暴力破解，但也会增加计算时间，需要在安全和用户体验间平衡。

5.2 处理大文件与流式加密

如前所述，一次性读取整个文件不适合大文件。下面是流式处理的思路：

def encrypt_file_streaming(input_path, output_path, key, chunk_size=64*1024): # 64KB 块 nonce = os.urandom(12) algorithm = algorithms.AES(key) cipher = Cipher(algorithm, mode=modes.GCM(nonce)) encryptor = cipher.encryptor() with open(input_path, 'rb') as fin, open(output_path, 'wb') as fout: fout.write(nonce) # 先写入 Nonce while True: chunk = fin.read(chunk_size) if not chunk: break encrypted_chunk = encryptor.update(chunk) fout.write(encrypted_chunk) # 最后一块处理 encrypted_final = encryptor.finalize() fout.write(encrypted_final) tag = encryptor.tag fout.write(tag) # 最后写入 Tag

解密时也需要对应的流式读取，先读 Nonce，然后循环读块解密，直到最后读取并验证 Tag。GCM 模式支持流式加密解密。

5.3 错误处理与日志记录

生产级工具需要完善的错误处理。使用try...except块捕获可能出现的异常，如文件不存在、权限错误、无效的密钥文件格式、认证失败等，并给出友好的错误信息。可以考虑添加日志记录功能，记录操作时间、文件名（不记录密钥和口令）和成功/失败状态，便于审计和排查问题。

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

在实际使用中，你可能会遇到以下问题：

Q1: 运行脚本时出现ModuleNotFoundError: No module named 'cryptography'A1:这说明cryptography库没有安装。请使用pip install cryptography安装。如果是在虚拟环境中，请确保已激活虚拟环境。

Q2: 在 Linux 上安装cryptography失败，提示缺少openssl/opensslv.h文件。A2:这是缺少 OpenSSL 的开发头文件。在 Ubuntu/Debian 上，运行sudo apt-get install libssl-dev。在 CentOS/RHEL 上，运行sudo yum install openssl-devel。

Q3: 解密时抛出cryptography.exceptions.InvalidTag异常。A3:这是最可能遇到的错误，意味着“验签”失败。请按以下顺序排查：

密钥错误：确认加密和解密使用的是完全相同的密钥文件。字节一个都不能差。
文件被篡改：确认加密后的文件在存储或传输过程中没有被修改。可以对比文件的哈希值（如 SHA256）。
Nonce/Tag 解析错误：确认加密和解密时，从文件读取和解析 Nonce、Tag、Ciphertext 的顺序和长度完全一致。如果加密时存储格式是Nonce(12)+Ciphertext+Tag(16)，解密时也必须按这个顺序和长度切割。
关联数据（AAD）不匹配：如果加密时调用了authenticate_additional_data()，解密时必须用完全相同的数据再次调用。

Q4: 加密后的文件比原文件大，这正常吗？A4:完全正常。因为 AES-GCM 加密后，我们不仅存储了密文，还额外存储了 Nonce（12字节）和认证标签 Tag（16字节）。所以加密文件会比原文件大 28 字节左右。这是为了安全必须付出的微小存储开销。

Q5: 我可以加密非文本文件（如图片、PDF）吗？A5:当然可以。这个工具处理的是字节流（'rb','wb'模式），与文件内容无关。你可以用它加密任何二进制文件。只需注意，加密后文件扩展名会失去意义，最好使用统一的扩展名（如.enc）来标识。

Q6: 如何备份我的密钥？A6:密钥的备份至关重要且风险极高。建议：