Metadata-Version: 2.4
Name: chacha-flow
Version: 1.0.0
Summary: Python library for ChaCha20 encryption with PNG-based key storage
Author: Security Team
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pillow>=10.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ChaCha Flow - Secure Encryption Library

A comprehensive Python library for symmetric encryption using ChaCha20 with advanced key management and PNG-based secure storage capabilities.

## Features

- **ChaCha20-Poly1305 AEAD Encryption**: Authenticated encryption with associated data
- **Secure Key Management**: Generate, store, and retrieve cryptographic keys
- **PNG-Based Key Storage**: Safely embed keys and sensitive data in PNG images using steganography
- **Master Key Encryption**: Optionally encrypt stored keys with a master key
- **Key Rotation**: Seamlessly rotate keys with version tracking
- **HMAC Verification**: Integrity verification of embedded data before deserialization
- **Security Logging**: Track security events without exposing sensitive data
- **File Permission Protection**: Automatic secure file permissions (Unix/Windows)

## Installation

### Prerequisites

- Python 3.8+
- pip

### Basic Installation

```bash
pip install chacha-flow
```


### Development Installation

```bash
pip install -e ".[dev]"
pytest  # Run tests
```

## Quick Start

### Basic Encryption/Decryption

```python
from chacha_flow import ChaChaCipher

# Generate a key
key = ChaChaCipher.generate_key()

# Create cipher
cipher = ChaChaCipher(key)

# Encrypt
plaintext = b"Secret message"
ciphertext = cipher.encrypt(plaintext)

# Decrypt
decrypted = cipher.decrypt(ciphertext)
assert decrypted == plaintext
```

### Key Management

```python
from chacha_flow import KeyManager

# Create key manager
key_manager = KeyManager()

# Generate and store a key
key = key_manager.generate_key()
key_manager.store_key(key, "my_app_key")

# Load key later
loaded_key = key_manager.load_key("my_app_key")

# Use loaded key
cipher = ChaChaCipher(loaded_key)
ciphertext = cipher.encrypt(b"Hello, World!")
```

### Store Key in PNG Image

```python
from chacha_flow import KeyManager

key_manager = KeyManager()
key = key_manager.generate_key()

# Store key in PNG (creates minimal PNG if no image provided)
key_manager.store_key_in_image(
    key,
    image_path="original.png",
    output_path="secret_key.png"
)

# Load key from PNG
loaded_key = key_manager.load_key_from_image("secret_key.png")
```

### Encrypted Key Storage with Master Key

```python
from chacha_flow import ChaChaCipher, KeyManager

# Generate master key
master_key = ChaChaCipher.generate_key()

# Create manager with encryption
key_manager = KeyManager(master_key=master_key)

# Keys are now stored encrypted
key = key_manager.generate_key()
key_manager.store_key(key, "prod_key")  # Encrypted automatically

# Load requires the same master key
loaded_key = key_manager.load_key("prod_key")
```

## Module Overview

### ChaChaCipher

ChaCha20-Poly1305 AEAD cipher implementation.

```python
from chacha_flow import ChaChaCipher

# Generate keys and nonces
key = ChaChaCipher.generate_key()        # 256-bit key
nonce = ChaChaCipher.generate_nonce()    # 96-bit nonce (auto-generated per message)

# Create cipher instance
cipher = ChaChaCipher(key)

# Encrypt
ciphertext = cipher.encrypt(plaintext)                    # Simple
ciphertext = cipher.encrypt(plaintext, associated_data)  # With AAD

# Decrypt
plaintext = cipher.decrypt(ciphertext)                    # Simple
plaintext = cipher.decrypt(ciphertext, associated_data)  # With AAD

# Validate key
is_valid = ChaChaCipher.is_valid_key(key)
```

**Security Properties:**
- 256-bit key strength
- 96-bit nonce per message
- Authenticated encryption prevents tampering
- Nonce is automatically included in ciphertext

### KeyManager

Centralized key management with multiple storage backends.

```python
from chacha_flow import KeyManager

# Initialize
km = KeyManager()                              # Default location
km = KeyManager(key_dir="/secure/keys")       # Custom location
km = KeyManager(master_key=master_key)        # With encryption

# Generate
key = km.generate_key()

# Store
km.store_key(key, "key_name", metadata={...})

# Load
key = km.load_key("key_name")

# List
keys = km.list_keys()

# Rotate
new_key = km.rotate_key("old_name", "new_name")

# Delete
km.delete_key("key_name")
km.delete_all_keys()  # WARNING: Irreversible

# Image storage
km.store_key_in_image(key, "original.png", "output.png")
key = km.load_key_from_image("output.png")
```

### ImageKeyStorage

Store serialized objects in PNG images with integrity verification.

```python
from chacha_flow import ImageKeyStorage

# Store object in image
ImageKeyStorage.store_key_in_image(
    {"key": b"...", "metadata": {...}},
    image_path="source.png",      # Optional, creates minimal PNG if omitted
    output_path="secret.png",
    hmac_key=master_key           # Optional, enables integrity verification
)

# Load object from image
obj = ImageKeyStorage.load_key_from_image(
    "secret.png",
    hmac_key=master_key           # Required if HMAC was used during storage
)
```

## Security Considerations

### Critical Security Warnings

⚠️ **Pickle Deserialization Risk**: `pickle` can execute arbitrary code during deserialization. **ONLY** load keys from **TRUSTED** image sources.

⚠️ **HMAC Verification**: When loading keys from images, always verify HMAC signature if available:

```python
# Good: Verify signature
key = ImageKeyStorage.load_key_from_image(
    "image.png",
    hmac_key=trusted_master_key  # Verification required
)

# Bad: No verification
key = ImageKeyStorage.load_key_from_image("untrusted_image.png")
```

⚠️ **Master Key Protection**: Protect master keys like passwords - if compromised, all encrypted keys are exposed.

### Best Practices

1. **Always verify image sources**: Only load from trusted origins
2. **Use HMAC when possible**: Enable signature verification
3. **Store securely**: Use restricted file permissions (automatic)
4. **Rotate regularly**: Change keys periodically
5. **Monitor logs**: Check for security events without exposing keys
6. **Backup keys**: Keep encrypted backups of critical keys
7. **Different keys per environment**: Use separate keys for dev/staging/production

### File Permissions

- **Unix/Linux**: Files automatically saved with `0o600` permissions (owner read/write only)
- **Windows**: Files saved with restricted access for the current user
- **Verification**: Permissions are checked before loading sensitive files

### Master Key Recommendations

```python
# Generate strong master key
master_key = ChaChaCipher.generate_key()

# Store it VERY securely:
# - Never hardcode in source
# - Use environment variables or secure vaults
# - Consider hardware security modules (HSM)

master_key = os.environ.get("CHACHA_MASTER_KEY")
if not master_key:
    raise ValueError("Master key not configured")

km = KeyManager(master_key=master_key)
```

## Configuration

Edit `chacha_flow/config.py` to customize:

```python
# Cryptographic parameters
CHACHA20_KEY_SIZE = 32          # 256-bit keys
CHACHA20_NONCE_SIZE = 12        # 96-bit nonces

# Image storage
MAX_IMAGE_SIZE_MB = 50          # Maximum image size
STORAGE_METHOD = "eof"          # "eof" (default) or "lsb"

# Key storage
DEFAULT_KEY_DIR = "~/.chacha_flow/keys"
KEY_PERMISSIONS = 0o600         # Unix file permissions

# Security
ENABLE_HMAC_VERIFICATION = True
HMAC_ALGORITHM = "sha256"

# Logging
LOG_LEVEL = "INFO"
```

## Examples

### Example 1: Secure Configuration Storage

```python
from chacha_flow import KeyManager, ChaChaCipher

# Generate and store configuration key
km = KeyManager()
config_key = km.generate_key()
km.store_key(config_key, "config_encryption_key")

# Encrypt configuration
config = {"database": "postgresql://...", "api_token": "secret"}
cipher = ChaChaCipher(config_key)
encrypted_config = cipher.encrypt(json.dumps(config).encode())

# Save encrypted config to file
with open("config.encrypted", "wb") as f:
    f.write(encrypted_config)

# Load and decrypt later
with open("config.encrypted", "rb") as f:
    encrypted_config = f.read()

cipher = ChaChaCipher(km.load_key("config_encryption_key"))
config = json.loads(cipher.decrypt(encrypted_config).decode())
```

### Example 2: Multi-Environment Key Management

```python
from chacha_flow import KeyManager

km = KeyManager()

# Generate environment-specific keys
for env in ["dev", "staging", "production"]:
    key = km.generate_key()
    km.store_key(key, f"app_key_{env}")

# Load based on environment
import os
env = os.environ["APP_ENV"]
key = km.load_key(f"app_key_{env}")
```

### Example 3: Backup Keys in Images

```python
from chacha_flow import KeyManager

km = KeyManager()

# Create backup of production key in image
prod_key = km.load_key("production")
km.store_key_in_image(
    prod_key,
    image_path="backup_template.png",
    output_path="/secure/backup/prod_key_backup.png"
)

# Restore from backup if needed
restored_key = km.load_key_from_image("/secure/backup/prod_key_backup.png")
km.store_key(restored_key, "production")
```

## Testing

Run the comprehensive test suite:

```bash
# Install test dependencies
pip install -e ".[dev]"

# Run all tests
pytest test_chacha_flow.py -v

# Run specific test class
pytest test_chacha_flow.py::TestChaChaCipher -v

# Run with coverage
pytest test_chacha_flow.py --cov=chacha_flow
```

## Running Examples

```bash
python examples.py
```

Output shows:
- Basic encryption/decryption
- Local key storage and retrieval
- Image-based key storage
- Encrypted key storage with master key
- Complete workflows
- Key rotation

## Architecture

```
chacha_flow/
├── __init__.py              # Package exports
├── chacha_cipher.py         # ChaCha20-Poly1305 encryption
├── key_manager.py           # Key generation and management
├── image_storage.py         # PNG steganography
├── config.py               # Configuration
└── utils.py                # Utilities (logging, security, HMAC)
```

## Logging

Security events are logged without exposing sensitive data:

```python
import logging
logging.basicConfig(level=logging.INFO)

# Logs include:
# - Key generation/rotation/deletion
# - Load/store operations
# - HMAC verification status
# - Invalid image/data detection
# - NO actual keys or plaintext
```

## Dependencies

- **cryptography** >= 41.0.0 - Cryptographic primitives
- **pillow** >= 10.0.0 - Image processing

## FAQ

**Q: Can I store other data besides keys?**
A: Yes! ImageKeyStorage can store any Python object via pickle.

```python
ImageKeyStorage.store_key_in_image(
    {"config": {...}, "settings": {...}},
    output_path="backup.png"
)
```

**Q: What if I lose my master key?**
A: All encrypted keys become unrecoverable. Always keep secure backups and use key rotation.

**Q: Is this suitable for production?**
A: Yes, but ensure proper key management procedures:
- Store master keys securely (vaults, HSM, etc.)
- Regularly rotate keys
- Monitor security logs
- Audit access patterns
- Use in combination with at-rest encryption

**Q: Can I use custom image processing?**
A: Yes, modify `image_storage.py` for custom steganography methods.

## Performance

- Key generation: ~1ms
- Encryption (1KB): ~2ms
- Decryption (1KB): ~2ms
- Image embedding: ~100ms (depends on image size)

## License

MIT License - See LICENSE file

## Contributing

Contributions welcome! Please:
1. Add tests for new features
2. Follow existing code style
3. Update documentation
4. Test on Python 3.8+
