AES-PKCS5 Encryption Library

1.0.4 verified Fri Apr 17 auth: no python

aes-pkcs5 is a Python library providing an implementation of the Advanced Encryption Standard (AES) using CBC and ECB modes, specifically incorporating the PKCS5 padding scheme. It is currently at version 1.0.4 and maintains an active release cadence, with recent updates focusing on Python version compatibility and modernization.

pip install aes-pkcs5

Common errors

error 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.

error 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'))).

error 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.

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}")