AES-PKCS5 Encryption Library

Common errors

• ModuleNotFoundError: No module named 'aes_pkcs5.algorithms'

  cause The `AESCipher` class is located within the `aes_pkcs5.algorithms` submodule, not directly under `aes_pkcs5`.
  fix Correct the import statement to `from aes_pkcs5.algorithms import AESCipher`.

• ValueError: Invalid AES key length. Key must be 16, 24, or 32 bytes long.

  cause The provided AES key (or IV) does not match the required byte lengths for AES (128-bit=16 bytes, 192-bit=24 bytes, 256-bit=32 bytes).
  fix Adjust your `key` and `iv` to be exactly 16, 24, or 32 bytes long. If using strings, ensure their UTF-8 encoded length matches these requirements (e.g., `len(key.encode('utf-8'))`).

• TypeError: argument of type 'bytes' is not iterable

  cause This error can occur in older versions (<1.0.3) if `bytes` objects are passed as key or IV, where `str` was expected. It can also occur if `encrypt` or `decrypt` functions receive unexpected types (though the library primarily operates on `str` inputs and outputs base64 encoded strings).
  fix Ensure `key` and `iv` are `str` for versions <1.0.3. For `encrypt`/`decrypt` operations, ensure your data is a `str` as the library is designed to take and return `str` by default (handling internal encoding/decoding).

Warnings

• breaking Python 3.8 and 3.7 support has been dropped in recent versions. Version 1.0.4 drops Python 3.8 support. Version 1.0.2 dropped Python 3.7 support.
  Fix: Upgrade your Python interpreter to 3.9 or higher, or pin to an older `aes-pkcs5` version if you must use an older Python (e.g., `pip install aes-pkcs5==1.0.1` for Python 3.8 compatibility).
• gotcha This library explicitly implements PKCS5 padding. While often interchangeable with PKCS7 for AES's fixed 16-byte block size, there are technical differences. If you need strict PKCS7 compatibility with other systems, this library might not be suitable without modification or additional handling.
  Fix: Ensure that the system you are interoperating with also expects PKCS5 padding. If PKCS7 is required, consider using `pycryptodome` or `cryptography` which offer more explicit padding options.
• gotcha Prior to version 1.0.3, passing `bytes` objects directly for the `key` or `iv` parameters of `AESCipher` could lead to `TypeError` as it primarily expected `str`. While 1.0.3+ supports `bytes`, consistency is key.
  Fix: For versions <1.0.3, ensure `key` and `iv` are `str` (e.g., `key.decode('utf-8')` if starting with bytes). For 1.0.3+, both `str` and `bytes` are accepted, but ensure consistent usage throughout your application.

Install

• pip install aes-pkcs5 Install latest version

Imports

• AESCipher

  from aes_pkcs5.algorithms import AESCipher

Quickstart

Initializes an AESCipher with a key and IV, then demonstrates encrypting and decrypting a simple string. The library handles base64 encoding/decoding of the encrypted output automatically.

from aes_pkcs5.algorithms import AESCipher

# Note: Key and IV should be securely generated and managed in production.
# For AES-128, key/IV length must be 16 bytes. For AES-256, 32 bytes.
# The library expects string input for key/IV by default, but bytes are also supported from v1.0.3+
key = 'This is a key123'
iv = 'This is an IV456'

cipher = AESCipher(key, iv)

data_to_encrypt = 'Hello, secure world!'

# Encrypt
encrypted_text = cipher.encrypt(data_to_encrypt)
print(f"Original: {data_to_encrypt}")
print(f"Encrypted (base64 encoded): {encrypted_text}")

# Decrypt
decrypted_text = cipher.decrypt(encrypted_text)
print(f"Decrypted: {decrypted_text}")