A pure Python implementation of common cryptographic algorithms for educational purposes.
This library provides implementations of various cryptographic algorithms including hash functions, symmetric and asymmetric encryption, and encoding schemes. The focus is on clear, understandable implementations that demonstrate how these algorithms work under the hood.
Note: This is an educational project. While the implementations are tested against reference libraries, they are not optimized for production use and have not undergone formal security audits.
This project uses uv for dependency management:
# Clone the repository
git clone <repository-url>
cd crypt
# Install dependencies
uv sync
# Install with dev dependencies
uv sync --group dev
# Install with test dependencies
uv sync --group test- Python >= 3.10
- uv (for dependency management)
from crypt.digest.SHA.sha2_256 import sha256
# SHA-256 hash
result = sha256(b"Hello, World!")
print(result.hex()) # dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986ffrom crypt.encrypt.symmetric_encrypt.block_cipher.aes import aes_encrypt, aes_decrypt
key = b"0123456789abcdef" # 16 bytes for AES-128
plaintext = b"Hello, World!!!!" # Must be 16 bytes (block size)
# Encrypt
ciphertext = aes_encrypt(plaintext, key)
print(f"Encrypted: {ciphertext.hex()}")
# Decrypt
decrypted = aes_decrypt(ciphertext, key)
print(f"Decrypted: {decrypted.decode()}")from crypt.encode.base64 import base64_encode, base64_decode
from crypt.encode.base58 import base58_encode, base58_decode
# Base64 encoding
data = b"Hello, World!"
encoded = base64_encode(data)
print(encoded) # SGVsbG8sIFdvcmxkIQ==
decoded = base64_decode(encoded)
print(decoded) # b"Hello, World!"
# Base58 encoding (commonly used in Bitcoin)
encoded = base58_encode(data)
print(encoded) # 72k1xXWG59fYdzSNoA
decoded = base58_decode(encoded)
print(decoded) # b"Hello, World!"from crypt.encrypt.asymmetric_encrypt.rsa import generate_keypair, rsa_encrypt, rsa_decrypt
# Generate RSA key pair
public_key, private_key = generate_keypair(key_size=2048)
# Encrypt
message = b"Hello, RSA!"
ciphertext = rsa_encrypt(message, public_key)
# Decrypt
decrypted = rsa_decrypt(ciphertext, private_key)
print(decrypted.decode()) # Hello, RSA!| Algorithm | Description | Security Status |
|---|---|---|
| MD Family | ||
| MD2 | 128-bit hash | Broken, legacy |
| MD4 | 128-bit hash | Broken, legacy |
| MD5 | 128-bit hash | Broken, legacy |
| MD6 | Variable-length hash | Experimental |
| SHA Family | ||
| SHA-0 | 160-bit hash | Broken |
| SHA-1 | 160-bit hash | Deprecated |
| SHA-224 | 224-bit hash | Secure |
| SHA-256 | 256-bit hash | Secure |
| SHA-384 | 384-bit hash | Secure |
| SHA-512 | 512-bit hash | Secure |
| SHA-512/224 | 224-bit truncated SHA-512 | Secure |
| SHA-512/256 | 256-bit truncated SHA-512 | Secure |
| SHA3-224 | Keccak-based 224-bit | Secure |
| SHA3-256 | Keccak-based 256-bit | Secure |
| SHA3-384 | Keccak-based 384-bit | Secure |
| SHA3-512 | Keccak-based 512-bit | Secure |
| Other Hashes | ||
| BLAKE2b | Fast cryptographic hash (64-byte) | Secure |
| BLAKE2s | Fast cryptographic hash (32-byte) | Secure |
| BLAKE3 | Modern fast hash | Secure |
| CRC8 / CRC12 | Cyclic redundancy checks | Non-cryptographic |
| CRC16 / CRC16-CCITT | Cyclic redundancy checks | Non-cryptographic |
| CRC32 / CRC32C | Cyclic redundancy checks | Non-cryptographic |
| CRC64 | Cyclic redundancy check | Non-cryptographic |
| Adler32 | Checksum algorithm | Non-cryptographic |
| FNV | Non-cryptographic hash | Non-cryptographic |
| Tiger | 192-bit hash | Legacy |
| RIPEMD-128 | 128-bit hash | Legacy |
| RIPEMD-160 | 160-bit hash | Legacy |
| Whirlpool | 512-bit hash | Legacy |
| SM3 | Chinese national standard hash | Secure |
| bcrypt | Password hashing | Secure |
| Poly1305 | Message authentication code | Secure |
- HMAC-MD5
- HMAC-SHA1
- HMAC-SHA256
| Algorithm | Description |
|---|---|
| CMAC | AES-based MAC (NIST SP 800-38B, RFC 4493) |
| SipHash | Fast keyed hash for hash-table DoS protection |
| Algorithm | Description |
|---|---|
| PBKDF2 | Password-Based Key Derivation Function 2 |
| scrypt | Memory-hard password hashing |
| Argon2 | Modern memory-hard password hashing |
| Algorithm | Block Size | Key Sizes | Security Status |
|---|---|---|---|
| AES | 128-bit | 128/192/256-bit | Secure |
| DES | 64-bit | 56-bit | Broken, legacy |
| 3DES (Triple DES) | 64-bit | 112/168-bit | Deprecated |
| Blowfish | 64-bit | 32-448-bit | Legacy |
| Twofish | 128-bit | 128/192/256-bit | Secure |
| Camellia | 128-bit | 128/192/256-bit | Secure |
| CAST5 (CAST-128) | 64-bit | 40-128-bit | Legacy |
| CAST6 (CAST-256) | 128-bit | 128/192/256-bit | AES candidate |
| RC5 | 64-bit | Variable | Legacy |
| RC6 | 128-bit | 128/192/256-bit | AES finalist |
| SM4 | 128-bit | 128-bit | Secure |
| PRESENT | 64-bit | 80/128-bit | Lightweight |
| Simon | Various | Various | NSA lightweight |
| Belt | 128-bit | 256-bit | Belarusian standard |
| Mode | Description | Authentication |
|---|---|---|
| ECB | Electronic Codebook (educational only) | No |
| CBC | Cipher Block Chaining | No |
| CFB | Cipher Feedback | No |
| OFB | Output Feedback | No |
| CTR | Counter mode | No |
| XTS | XEX-based tweaked-codebook with ciphertext stealing | No |
| EAX | Authenticated encryption with associated data (AEAD) | Yes |
| OCB | Offset Codebook Mode v3 (AEAD, RFC 7253) | Yes |
Note: GCM and CCM modes are stub implementations using SHA-256 keystream instead of proper CTR mode. They are marked for development only.
| Scheme | Description |
|---|---|
| PKCS7 | PKCS #7 padding |
| ANSI X.923 | ANSI X9.23 padding |
| Algorithm | Description | Security Status |
|---|---|---|
| ChaCha20 | Modern stream cipher | Secure |
| ChaCha20-Poly1305 | AEAD construction (RFC 8439, TLS 1.3) | Secure |
| Salsa20 | Predecessor to ChaCha20 | Secure |
| RC4 | Legacy stream cipher | Broken |
| SEAL | Software-optimized encryption algorithm | Legacy |
| Rabbit | High-performance stream cipher | Secure |
| Trivium | Hardware-oriented stream cipher | Secure |
Note: ZUC is a stub (placeholder) - not yet implemented.
| Algorithm | Type |
|---|---|
| Playfair | Digraph substitution |
| Rail Fence | Transposition cipher |
| Algorithm | Description |
|---|---|
| RSA | Rivest-Shamir-Adleman encryption and signatures |
| RSA-PSS | Probabilistic Signature Scheme |
| DSA | Digital Signature Algorithm |
| ECC | Elliptic Curve Cryptography |
| ECDH | Elliptic Curve Diffie-Hellman |
| Ed25519 | Edwards-curve Digital Signature Algorithm |
| X25519 | Elliptic Curve Diffie-Hellman (Curve25519) |
| Diffie-Hellman | Key exchange protocol |
| ElGamal | Discrete logarithm-based encryption |
| Paillier | Additive homomorphic encryption |
| NTRU | Lattice-based post-quantum encryption |
| Encoding | Description |
|---|---|
| Base16 (Hex) | Hexadecimal encoding |
| Base32 | RFC 4648 Base32 |
| Base36 | Alphanumeric encoding (0-9, A-Z) |
| Base58 | Bitcoin-style encoding (no 0/O/I/l) |
| Base62 | Alphanumeric encoding |
| Base64 | RFC 4648 Base64 |
| Base85 | ASCII85 encoding |
| Base91 | High-density encoding |
| Base92 | Dense binary-to-text |
| Hex2Bin | Binary-hexadecimal conversion |
| Morse Code | Telegraph encoding |
| URL Encoding | Percent-encoding |
| HTML Entities | Character entity encoding |
| Quoted-Printable | MIME email-safe encoding |
| ROT47 | ASCII shift cipher encoding |
| ASCII | ASCII encoding utilities |
IMPORTANT: This library is intended for educational purposes only.
- Not for Production: These implementations are not optimized for performance and have not undergone formal security audits.
- Timing Attacks: Pure Python implementations may be vulnerable to timing attacks due to non-constant-time operations.
- Deprecated Algorithms: Some implemented algorithms (MD5, SHA-1, DES, RC4) are cryptographically broken or deprecated. They are included for educational and legacy compatibility purposes only.
- Stub Implementations: GCM, CCM, and ZUC are stub implementations and should not be used for production cryptography.
- Use Established Libraries: For production use, please use well-established
libraries such as:
- cryptography
- pycryptodome
- Python's built-in
hashlibandsecretsmodules
See SECURITY.md for detailed security considerations.
The project includes comprehensive tests for all implementations:
# Run all tests with coverage
uv run pytest
# Run specific test file
uv run pytest tests/digest/test_sha.py
# Run without parallelization (for debugging)
uv run pytest -n0
# Run with verbose output
uv run pytest -vTests validate implementations against reference libraries (hashlib, pycryptodome,
cryptography) to ensure correctness. Coverage target: 90%+.
# Run linting
uv run ruff check .
# Fix linting issues
uv run ruff check --fix .
# Format code
uv run ruff format .
# Type checking
uv run pyright
# Run all quality checks
uv run poe fullsrc/crypt/
├── digest/ # Hash algorithms and message authentication
│ ├── CRC/ # CRC8, CRC12, CRC16, CRC32, CRC32C, CRC64
│ ├── HMAC/ # HMAC-MD5, HMAC-SHA1, HMAC-SHA256, CMAC
│ ├── KDF/ # PBKDF2, scrypt, Argon2
│ ├── MD/ # MD2, MD4, MD5, MD6
│ ├── SHA/ # SHA-0, SHA-1, SHA-2, SHA-3 family
│ └── SHAKE/ # SHAKE128, SHAKE256
├── encode/ # Encoding schemes (Base16/32/36/58/62/64/85/91/92, etc.)
└── encrypt/ # Encryption algorithms
├── asymmetric_encrypt/ # RSA, ECC, DSA, ECDH, Ed25519, X25519, ElGamal, Paillier
├── end2end_encrypt/ # End-to-end encryption protocols (STUB)
└── symmetric_encrypt/ # Secret-key cryptography
├── block_cipher/ # AES, DES, Blowfish, Twofish, Camellia, SM4, etc.
├── modes/ # ECB, CBC, CFB, OFB, CTR, XTS, EAX, OCB
└── stream_cipher/ # ChaCha20, Salsa20, RC4, Rabbit, Trivium, etc.
tests/ # Comprehensive test suite
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- FIPS 180-4 - Secure Hash Standard (SHS)
- FIPS 197 - Advanced Encryption Standard (AES)
- RFC 1321 - The MD5 Message-Digest Algorithm
- RFC 2104 - HMAC: Keyed-Hashing for Message Authentication
- RFC 2898 - PKCS #5: Password-Based Cryptography
- RFC 4648 - Base16, Base32, and Base64 Encodings
- RFC 7748 - Elliptic Curves for Security
- RFC 8032 - Edwards-Curve Digital Signature Algorithm
This project is open source under the MIT License. See LICENSE for details.
This project is inspired by and references implementations from:
- pycryptodome
- cryptography
- Various academic papers and RFC specifications
Disclaimer: The authors are not responsible for any misuse of this software. Always consult with security professionals when implementing cryptography in production systems.