PyAES: Pure Python AES Implementation

Warnings

• gotcha AES key lengths must be 16, 24, or 32 bytes (for AES-128, AES-192, AES-256 respectively). Initialization Vector (IV) for CBC mode must be 16 bytes. Providing incorrect lengths will result in errors or insecure operation.
  Fix: Ensure `key` is 16, 24, or 32 bytes long, and `iv` (for CBC/CTR/OFB) is 16 bytes long. Use `os.urandom()` for cryptographically secure random values.
• breaking The stream API (e.g., `encrypt_stream`, `decrypt_stream`) was broken in version 1.5.0 and fixed in 1.6.0. Users upgrading from 1.5.0 to 1.6.0 will find their stream operations now function correctly, which might be a 'breaking change' if their code had workarounds for the 1.5.0 bug.
  Fix: Ensure you are using version 1.6.0 or higher for reliable stream API functionality. Review code that interacted with the stream API in 1.5.0 as workarounds may no longer be necessary or compatible.
• gotcha PyAES uses simple zero-padding by default when input data is not a multiple of the AES block size (16 bytes). This can lead to security vulnerabilities (e.g., padding oracle attacks) or data loss if the original plaintext legitimately ends with null bytes, as zero-padding cannot distinguish between actual nulls and padding nulls.
  Fix: For robust applications, implement a cryptographically secure padding scheme like PKCS7 or ISO 10126 before encryption and unpadding after decryption, rather than relying on `pyaes`'s default zero-padding.
• gotcha Reusing the same Initialization Vector (IV) with the same key for multiple encryptions in CBC mode significantly compromises confidentiality, making the encryption vulnerable to attacks. A unique, unpredictable IV is crucial for each encryption operation.
  Fix: Always generate a new, cryptographically random IV (e.g., `os.urandom(16)`) for every distinct encryption operation with the same key in CBC mode. Store and transmit the IV alongside the ciphertext (it does not need to be secret).

Install

• pip install pyaes Install PyAES

Imports

• AESModeOfOperationCBC

  from pyaes import AESModeOfOperationCBC

• AESModeOfOperationCTR

  from pyaes import AESModeOfOperationCTR

• AES

  from pyaes import AES

  Use this for the raw block cipher; typically prefer mode-of-operation classes for common use cases.

Quickstart

This example demonstrates encrypting and decrypting data using AES in CBC mode with a 256-bit key. It highlights the use of `AESModeOfOperationCBC` and the necessity of providing a unique IV for each encryption operation. PyAES uses zero-padding by default if the plaintext length is not a multiple of the block size.

import pyaes
import os

# AES in CBC mode (with default zero-padding)
key = os.urandom(32) # 256-bit key
iv = os.urandom(16)  # 128-bit Initialization Vector

aes_cbc_encrypt = pyaes.AESModeOfOperationCBC(key, iv=iv)
plaintext = b"This is some plaintext to encrypt. It will be zero-padded if not a multiple of 16 bytes."
ciphertext = aes_cbc_encrypt.encrypt(plaintext)

# Decrypt using a new AES object with the same key and IV
aes_cbc_decrypt = pyaes.AESModeOfOperationCBC(key, iv=iv)
decrypted_text = aes_cbc_decrypt.decrypt(ciphertext)

print(f"Original: {plaintext}")
print(f"Encrypted: {ciphertext.hex()}")
print(f"Decrypted: {decrypted_text}")

assert decrypted_text == plaintext