pyAesCrypt

6.1.1 · active · verified Thu Apr 16

pyAesCrypt is a Python library (version 6.1.1) for encrypting and decrypting files and streams using the AES Crypt format (version 2). It provides a straightforward API for secure file and stream operations with AES encryption, often seeing patch and minor releases and occasional major updates that introduce breaking changes or significant features.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'
```
cause The input file specified for encryption or decryption does not exist at the given path.

fix Verify the file path and name. Ensure the input file exists before calling `encryptFile` or `decryptFile`.
```
pyAesCrypt.AESCryptException: BadSignatureException: Wrong password or file corrupted
```
cause The provided password does not match the one used during encryption, or the encrypted file is corrupted/not a valid pyAesCrypt file.

fix Double-check the password. Ensure you are using the correct file and that it hasn't been tampered with. If decrypting old files, consider setting `pyAesCrypt.AESCryptVersion = 0`.
```
PermissionError: [Errno 13] Permission denied: 'output.aes'
```
cause The Python process does not have write permissions to the specified output directory or file.

fix Ensure the directory where the output file is to be created exists and that the current user/process has write permissions to it. Change the output path to a writable location if necessary.
```
ValueError: Password too weak
```
cause Starting from version 6.0.0, pyAesCrypt enforces stricter password complexity rules, and the provided password did not meet them.

fix Choose a stronger password. It should typically be longer, and include a mix of uppercase and lowercase letters, numbers, and special characters.

Warnings

breaking Public API exceptions for I/O errors were changed in version 5.0.0. Code catching specific `IOError` types might need to be updated to catch `pyAesCrypt.AESCryptException` or more specific custom exceptions introduced by the library.
Fix: Review error handling code. Replace general `IOError` catches with `pyAesCrypt.AESCryptException` or more specific exception types documented for pyAesCrypt.
breaking Version 6.0.0 introduced an updated password complexity check. Passwords considered weak in newer versions might have worked in older ones, potentially causing `ValueError: Password too weak` during encryption attempts. Additionally, a default buffer size was set, which might slightly alter performance for applications that previously relied on unspecified buffer sizes.
Fix: Ensure all passwords meet modern complexity standards (e.g., length, mixed characters). Explicitly set `bufferSize` if your application requires specific memory usage or performance characteristics.
gotcha By default, `pyAesCrypt` encrypts and decrypts files using the AES Crypt format version 2. If you need to decrypt files created with very old versions of `pyAesCrypt` (0.x.x series), you must explicitly set `pyAesCrypt.AESCryptVersion = 0` *before* attempting decryption, otherwise decryption will likely fail or yield corrupted data.
Fix: For compatibility with old files, add `pyAesCrypt.AESCryptVersion = 0` before calling decryption functions. Example: `pyAesCrypt.AESCryptVersion = 0; pyAesCrypt.decryptFile(...)`
gotcha A bug in stream encryption was fixed in version 6.1.1. Users on older 6.x.x versions (e.g., 6.0.0, 6.1.0) might encounter issues with corrupted output when using `encryptStream` or `decryptStream` functions.
Fix: Upgrade `pyaescrypt` to version 6.1.1 or newer to benefit from the stream encryption fix: `pip install --upgrade pyaescrypt`.

Install

pip install pyaescrypt Install latest version

Imports

pyAesCrypt
```
import pyAesCrypt
```

encryptFile

import pyAesCrypt
pyAesCrypt.encryptFile(...)

decryptFile

import pyAesCrypt
pyAesCrypt.decryptFile(...)

encryptStream

import pyAesCrypt
pyAesCrypt.encryptStream(...)

decryptStream

import pyAesCrypt
pyAesCrypt.decryptStream(...)

AESCryptException

from pyAesCrypt import AESCryptException

Quickstart

This quickstart demonstrates how to encrypt and decrypt a file using `pyAesCrypt.encryptFile` and `pyAesCrypt.decryptFile`. It creates a dummy text file, encrypts it, decrypts it, prints the decrypted content, and then cleans up the temporary files. Remember to use a strong password and manage it securely.

import pyAesCrypt
import os

# --- Setup (create dummy file) ---
input_file = "data.txt"
encrypted_file = "data.aes"
decrypted_file = "data.txt.out"
password = os.environ.get('AESCRYPT_PASSWORD', 'mySuperSecretPassword123') # Replace with strong password
buffer_size = 64 * 1024 # 64KB

with open(input_file, 'w') as f:
    f.write('This is a test message to be encrypted.')

print(f"Original file '{input_file}' created.")

# --- Encryption ---
try:
    pyAesCrypt.encryptFile(input_file, encrypted_file, password, buffer_size)
    print(f"File '{input_file}' encrypted to '{encrypted_file}'.")

    # --- Decryption ---
    pyAesCrypt.decryptFile(encrypted_file, decrypted_file, password, buffer_size)
    print(f"File '{encrypted_file}' decrypted to '{decrypted_file}'.")

    with open(decrypted_file, 'r') as f:
        content = f.read()
        print(f"Decrypted content: '{content}'")

    # Verify content
    with open(input_file, 'r') as f_orig, open(decrypted_file, 'r') as f_dec:
        if f_orig.read() == f_dec.read():
            print("Decryption successful and content matches original.")
        else:
            print("WARNING: Decrypted content does NOT match original!")

except pyAesCrypt.AESCryptException as e:
    print(f"An encryption/decryption error occurred: {e}")
except FileNotFoundError as e:
    print(f"File not found error: {e}")
except PermissionError as e:
    print(f"Permission error: {e}")
finally:
    # --- Cleanup ---
    for f in [input_file, encrypted_file, decrypted_file]:
        if os.path.exists(f):
            os.remove(f)
            print(f"Cleaned up '{f}'.")

view raw JSON →