oxifish 0.1.1

Python bindings for the RustCrypto Twofish block cipher implementation

oxifish

Python bindings for the RustCrypto Twofish block cipher implementation.

Installation

pip install oxifish

Usage

CBC Mode (with padding)

import secrets
from oxifish import TwofishCBC, pad, unpad, PaddingStyle

key = secrets.token_bytes(16)  # 16, 24, or 32 bytes
iv = secrets.token_bytes(16)   # MUST be unique per encryption

cipher = TwofishCBC(key)

# Encrypt with PKCS7 padding
plaintext = b'Hello, World!'
padded = pad(plaintext, cipher.block_size, PaddingStyle.Pkcs7)
ciphertext = cipher.encrypt(padded, iv)

# Decrypt
decrypted = cipher.decrypt(ciphertext, iv)
result = unpad(decrypted, cipher.block_size, PaddingStyle.Pkcs7)
# b'Hello, World!'

# Store IV with ciphertext (IV is not secret)
encrypted_message = iv + ciphertext

Streaming API

For processing large data or when you need incremental encryption:

from oxifish import TwofishCBC, pad, PaddingStyle

cipher = TwofishCBC(key)

# Streaming encryption
enc = cipher.encryptor(iv)
ciphertext = enc.update(pad(chunk1, 16, PaddingStyle.Pkcs7))
ciphertext += enc.update(pad(chunk2, 16, PaddingStyle.Pkcs7))
ciphertext += enc.finalize()

# Streaming decryption
dec = cipher.decryptor(iv)
plaintext = dec.update(ciphertext)
plaintext += dec.finalize()

CTR Mode (no padding needed)

import secrets
from oxifish import TwofishCTR

key = secrets.token_bytes(16)
nonce = secrets.token_bytes(16)  # MUST be unique per encryption

cipher = TwofishCTR(key)
ciphertext = cipher.encrypt(b'any length data', nonce)
plaintext = cipher.decrypt(ciphertext, nonce)

ECB Mode (single blocks only)

import secrets
from oxifish import TwofishECB

key = secrets.token_bytes(16)
cipher = TwofishECB(key)
ciphertext = cipher.encrypt_block(b'16 byte block!!')
plaintext = cipher.decrypt_block(ciphertext)

Warning: ECB mode does NOT provide semantic security. Use CBC, CTR, or other modes for general encryption.

Available Modes

Mode	Padding	Use Case
TwofishCBC	Use pad()/unpad()	General encryption
TwofishCTR	Not needed	Stream encryption
TwofishCFB	Not needed	Stream encryption
TwofishOFB	Not needed	Stream encryption
TwofishECB	N/A (block-level)	Building blocks, compatibility

Padding Styles

Use the standalone pad() and unpad() functions with PaddingStyle:

• PaddingStyle.Pkcs7 - Standard PKCS#7 padding (recommended)
• PaddingStyle.Zeros - Zero padding (cannot roundtrip data ending with zeros)
• PaddingStyle.Iso7816 - ISO/IEC 7816-4 padding
• PaddingStyle.AnsiX923 - ANSI X9.23 padding

Security

This library is primarily intended for compatibility with existing systems that require Twofish, such as KeePass databases.

Note: Twofish is not constant-time due to key-dependent S-boxes. This is fine for local file decryption but not suitable for server-side encryption where timing attacks are feasible. For new projects, prefer AES-GCM or ChaCha20-Poly1305.

See SECURITY.md for vulnerability reporting and details on key zeroization.

Development

Requires Rust and Python 3.10+.

# Install uv if you haven't
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install maturin
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install maturin

# Build and install in development mode
maturin develop

# Run tests
uv pip install pytest
pytest

License

MIT License. See LICENSE for details.

This project uses the RustCrypto twofish crate which is dual-licensed under MIT/Apache-2.0. We use it under the MIT license.