secure-crypto 1.0.2

A cryptography library with strong security defaults for non-expert developers

c r y p t o L i b 🔐

A Python cryptography library designed for non-expert developers with strong security defaults and safe APIs.

⚡ Quick Start

from secure_crypto import SimpleCrypto

# Encrypt a file with password (easiest method!)
SimpleCrypto.encrypt_file_with_password("document.pdf", "MyStrongPassword123!")

# Decrypt it back
SimpleCrypto.decrypt_file_with_password("document.pdf.encrypted", "MyStrongPassword123!")

🎯 Features

✅ What Makes This Library Safe

• Strong Defaults Only: Minimum 3072-bit RSA keys, 256-bit AES
• Modern Algorithms: RSA-OAEP, AES-256-GCM, PBKDF2 with 600k iterations
• Authenticated Encryption: Detects tampering automatically
• Clear Error Messages: Guides you when something is wrong
• No Weak Crypto: Weak algorithms and key sizes are rejected
• Hybrid Encryption: Efficient encryption for large files

🚀 Main Features

1. Password-Based File Encryption - Easiest way to secure files
2. RSA Public Key Encryption - Share files securely with others
3. Digital Signatures - Verify authenticity of messages
4. Secure Key Generation - Create strong cryptographic keys
5. Hybrid Encryption - RSA + AES for large files
6. Key Derivation - Turn passwords into encryption keys safely

📦 Installation

pip install cryptography --break-system-packages

Then just copy secure_crypto.py to your project!

📚 Usage Guide

1. Password-Based File Encryption (Simplest!)

Perfect for encrypting your own files.

from secure_crypto import SimpleCrypto

# Encrypt
SimpleCrypto.encrypt_file_with_password(
    file_path="my_secrets.txt",
    password="VeryStrongPassword123!@#"
)
# Creates: my_secrets.txt.encrypted

# Decrypt
SimpleCrypto.decrypt_file_with_password(
    encrypted_file="my_secrets.txt.encrypted",
    password="VeryStrongPassword123!@#"
)

When to use:

• Encrypting your own files
• Backup encryption
• Simple file protection

Pros: No key management needed, just remember password Cons: Must share password securely if sharing with others

---

2. RSA Public Key Encryption

Perfect for sharing encrypted files with specific people.

from secure_crypto import SimpleCrypto

# Step 1: Everyone generates their own keys (one-time setup)
alice_keys = SimpleCrypto.create_new_keys(save_to_dir="./alice_keys")
bob_keys = SimpleCrypto.create_new_keys(save_to_dir="./bob_keys")

# Step 2: Alice encrypts a message for Bob using Bob's public key
encrypted_msg = SimpleCrypto.encrypt_message(
    message="Meet at 3pm",
    public_key_path="./bob_keys/public_key.pem"
)

# Step 3: Bob decrypts with his private key
decrypted_msg = SimpleCrypto.decrypt_message(
    encrypted_message=encrypted_msg,
    private_key_path="./bob_keys/private_key.pem"
)

When to use:

• Sending encrypted messages to specific people
• Sharing files with colleagues
• When recipients already have key pairs

Pros: No need to share passwords Cons: Requires key management

---

3. Digital Signatures

Prove a message came from you and wasn't tampered with.

from secure_crypto import RSAEncryption, SecureKeyGenerator

# Generate your keys
private_key, public_key = SecureKeyGenerator.generate_rsa_keypair()

# Sign a message
signer = RSAEncryption(private_key_pem=private_key)
message = b"This is my authentic message"
signature = signer.sign(message)

# Anyone can verify with your public key
verifier = RSAEncryption(public_key_pem=public_key)
is_authentic = verifier.verify(message, signature)
print(f"Message authentic: {is_authentic}")  # True

# Tampering detection
tampered = b"This is a FAKE message"
is_authentic = verifier.verify(tampered, signature)
print(f"Tampered message authentic: {is_authentic}")  # False

When to use:

• Proving authorship of documents
• Ensuring message integrity
• Building trust systems

---

4. Hybrid Encryption (Advanced)

Encrypt large files efficiently by combining RSA and AES.

from secure_crypto import RSAEncryption, SecureFileEncryption, SecureKeyGenerator

# Generate recipient's keys
private_key, public_key = SecureKeyGenerator.generate_rsa_keypair()

# Encrypt a large file
rsa = RSAEncryption(public_key_pem=public_key)
encryptor = SecureFileEncryption(rsa)
metadata = encryptor.encrypt_file("large_video.mp4", "large_video.mp4.enc")

# Decrypt with private key
rsa_decrypt = RSAEncryption(private_key_pem=private_key)
decryptor = SecureFileEncryption(rsa_decrypt)
decryptor.decrypt_file("large_video.mp4.enc", "large_video_decrypted.mp4")

How it works:

1. Generates random AES key for the file
2. Encrypts file with fast AES-256
3. Encrypts AES key with RSA public key
4. Stores both encrypted data and encrypted key

When to use:

• Large files (videos, databases, etc.)
• Best security + performance balance

---

5. Direct AES Encryption

For encrypting data in memory or streaming.

from secure_crypto import AESEncryption, SecureKeyGenerator

# Generate or load a key
key = SecureKeyGenerator.generate_aes_key()
aes = AESEncryption(key)

# Encrypt data
data = b"Sensitive information"
encrypted = aes.encrypt(data)

# encrypted contains: {'ciphertext', 'nonce', 'tag'}
# All three are needed for decryption!

# Decrypt
decrypted = aes.decrypt(
    encrypted['ciphertext'],
    encrypted['nonce'],
    encrypted['tag']
)

When to use:

• Encrypting data in memory
• Building custom encryption workflows
• Need fine-grained control

---

6. Key Derivation from Passwords

Turn passwords into encryption keys securely.

from secure_crypto import SecureKeyGenerator

# Derive key from password
password = "UserPassword123!"
key, salt = SecureKeyGenerator.derive_key_from_password(password)

# Save the salt! You need it to derive the same key later
# The salt should be stored with encrypted data (not secret)

# Later: derive same key from same password + salt
key_again, _ = SecureKeyGenerator.derive_key_from_password(password, salt)
# key == key_again ✅

When to use:

• Building custom password-based encryption
• User authentication systems
• Key derivation for applications

---

🔒 Security Features

Strong Defaults

Feature	Setting	Why
RSA Key Size	4096 bits (min 3072)	Future-proof against quantum computers
AES Key Size	256 bits	Maximum AES security
Padding	RSA-OAEP with SHA-256	Prevents padding oracle attacks
AES Mode	GCM (Authenticated)	Detects tampering automatically
Key Derivation	PBKDF2-SHA256	Industry standard
KDF Iterations	600,000	OWASP 2023 recommendation

What's Blocked

• ❌ RSA keys below 3072 bits
• ❌ Weak padding schemes (PKCS#1 v1.5)
• ❌ Unauthenticated encryption modes
• ❌ Weak key derivation functions

Automatic Protection Against

• ✅ Padding Oracle Attacks - Uses OAEP padding
• ✅ Tampering - GCM mode authenticates data
• ✅ Replay Attacks - Random nonces for each encryption
• ✅ Weak Keys - Enforces minimum key sizes
• ✅ Password Cracking - High iteration count for PBKDF2

---

🎓 API Reference

SimpleCrypto (Easiest Interface)

class SimpleCrypto:
    @staticmethod
    def create_new_keys(save_to_dir: Optional[Path] = None) -> dict
    
    @staticmethod
    def encrypt_file_with_password(file_path: Path, password: str, 
                                   output_path: Optional[Path] = None) -> Path
    
    @staticmethod
    def decrypt_file_with_password(encrypted_file: Path, password: str,
                                   output_path: Optional[Path] = None) -> Path
    
    @staticmethod
    def encrypt_message(message: str, public_key_path: Path) -> str
    
    @staticmethod
    def decrypt_message(encrypted_message: str, private_key_path: Path) -> str

SecureKeyGenerator

class SecureKeyGenerator:
    @staticmethod
    def generate_rsa_keypair(key_size: int = 4096) -> Tuple[bytes, bytes]
    
    @staticmethod
    def generate_aes_key() -> bytes
    
    @staticmethod
    def derive_key_from_password(password: str, salt: Optional[bytes] = None) 
        -> Tuple[bytes, bytes]

RSAEncryption

class RSAEncryption:
    def __init__(self, private_key_pem: Optional[bytes] = None,
                 public_key_pem: Optional[bytes] = None)
    
    def encrypt(self, plaintext: bytes) -> bytes
    def decrypt(self, ciphertext: bytes) -> bytes
    def sign(self, message: bytes) -> bytes
    def verify(self, message: bytes, signature: bytes) -> bool

AESEncryption

class AESEncryption:
    def __init__(self, key: Optional[bytes] = None)
    
    def encrypt(self, plaintext: bytes) -> dict  # Returns {ciphertext, nonce, tag}
    def decrypt(self, ciphertext: bytes, nonce: bytes, tag: bytes) -> bytes

SecureFileEncryption

class SecureFileEncryption:
    def __init__(self, rsa_encryption: Optional[RSAEncryption] = None)
    
    def encrypt_file(self, input_path: Path, output_path: Path,
                    password: Optional[str] = None) -> dict
    
    def decrypt_file(self, input_path: Path, output_path: Path,
                    password: Optional[str] = None) -> dict

---

🛡️ Best Practices

✅ DO

1. Use password encryption for your own files

   SimpleCrypto.encrypt_file_with_password("data.txt", "StrongPassword123!")
   

2. Use RSA for sharing with others

   SimpleCrypto.encrypt_message("Secret", "recipient_public_key.pem")
   

3. Keep private keys secret and backed up

   • Store in secure location
   • Never commit to git
   • Make encrypted backups

4. Use strong passwords

   • At least 12 characters
   • Mix of letters, numbers, symbols
   • Unique per file/system

5. Verify signatures for important messages

   is_authentic = rsa.verify(message, signature)
   if not is_authentic:
       print("WARNING: Message may be tampered!")
   

❌ DON'T

1. Don't use weak passwords

   • Bad: "password123", "qwerty", "admin"
   • Good: "My@Dog#Ate$Pizza!2024"

2. Don't share private keys

   • Only share public keys
   • Private keys should never leave your system

3. Don't reuse passwords across files

   • Each important file should have unique password
   • Use password manager to track

4. Don't lose the salt or nonce

   • These are needed for decryption
   • The library handles this automatically

5. Don't ignore authentication failures

   • If decryption fails, data may be corrupted or tampered
   • Don't use unauthenticated data

---

📊 Performance

Operation	Small File (1 MB)	Large File (100 MB)
Password Encrypt	~50 ms	~1.2 sec
Password Decrypt	~50 ms	~1.0 sec
RSA Key Gen (4096)	~2 sec	-
Hybrid Encrypt	~60 ms	~1.3 sec
Hybrid Decrypt	~55 ms	~1.1 sec

Tested on modern CPU. Times approximate.

---

🐛 Common Issues

Issue: "Key size is insecure"

# ❌ This will fail:
SecureKeyGenerator.generate_rsa_keypair(key_size=2048)

# ✅ Use minimum 3072 or recommended 4096:
SecureKeyGenerator.generate_rsa_keypair(key_size=4096)

Issue: "Data too large for RSA encryption"

# ❌ RSA can only encrypt small data (~470 bytes for 4096-bit key)
rsa.encrypt(large_file_content)

# ✅ Use password or hybrid encryption for files:
SimpleCrypto.encrypt_file_with_password("large_file.zip", "password")

Issue: "Wrong password or corrupted file"

• Check password is exactly correct (case-sensitive)
• Ensure encrypted file wasn't modified
• Verify you're using the right encrypted file

Issue: "No private key available"

• Make sure you're using private key for decryption
• Public keys can only encrypt, not decrypt

---

🎯 Use Cases

Personal Use

• Encrypt sensitive documents before cloud backup
• Protect tax records and financial documents
• Secure personal photos and videos

Developers

• Add encryption to your application
• Build secure file storage systems
• Implement digital signature verification

---

🔐 Additional Security Features

Secure File Deletion

from secure_crypto import secure_delete_file

# Overwrites file with random data before deletion
secure_delete_file("sensitive.txt", passes=3)

---

🤝 Contributing

Contributions welcome! Please ensure:

• All security defaults remain strong
• Add tests for new features
• Update documentation
• Follow existing code style

---

⚠️ Security Note

This library provides strong security defaults, but remember:

• No crypto library is perfect
• Keep your keys and passwords safe
• Regular security updates are important
• Consult security experts for critical applications

---

📚 Learn More

• OWASP Cryptographic Storage Cheat Sheet
• Python Cryptography Library Docs
• NIST Cryptographic Standards

---

Made with 🔒 for secure and simple cryptography