# Frequently Asked Questions

## General Questions

### What is Irene Cipher?

Irene Cipher is a production-grade cryptographic library written in Rust and exposed as a Python package. It provides secure, authenticated encryption for text and files using modern, audited cryptographic primitives.

### Is it secure?

Yes, with caveats:
- Uses audited cryptographic libraries (RustCrypto)
- Implements modern algorithms (XChaCha20-Poly1305, Argon2id)
- Follows security best practices
- **However**: Not yet formally audited
- **Use at your own risk** for production systems
- Consider professional security audit for critical applications

### Why another crypto library?

- **Modern algorithms**: Uses XChaCha20-Poly1305 (not AES-GCM)
- **Performance**: Written in Rust, much faster than pure Python
- **Memory efficient**: Streams large files without loading into RAM
- **Pythonic**: Clean API, not just raw crypto primitives
- **Type safe**: Full type hints and comprehensive docs

## Usage Questions

### How do I install it?

```bash
pip install irene-cipher
```

### What Python versions are supported?

Python 3.8 and above on Windows, macOS, and Linux.

### Can I use it with async/await?

Currently no. The library is synchronous. For async support, you can use:

```python
import asyncio
import irene_cipher

async def encrypt_async(text, password):
    loop = asyncio.get_event_loop()
    return await loop.run_in_executor(
        None, irene_cipher.encrypt_text, text, password
    )
```

### How do I encrypt large files?

Use `encrypt_file()` - it automatically uses streaming:

```python
import irene_cipher

# Works with files of any size (KB to multi-GB)
irene_cipher.encrypt_file("large.mp4", "large.mp4.enc", "password")
```

Memory usage stays constant regardless of file size.

### Can I use a key instead of a password?

The current API only supports password-based encryption. If you have a key:

1. Use it as a password (not ideal - no key derivation)
2. Or use Rust API directly with raw key
3. Future version may add key-based API

### What's the performance like?

- **Key derivation**: ~50ms (intentionally slow for security)
- **Encryption**: ~67 MB/s
- **Decryption**: ~67 MB/s

File operations are typically I/O bound, not CPU bound.

## Security Questions

### Is it safe to reuse passwords?

**No.** Always use unique passwords for different data. Password reuse is a security risk.

### What happens if I lose my password?

**Data is permanently lost.** There is no recovery mechanism. This is by design - no backdoors.

### Can someone crack the encryption?

With a strong password: extremely unlikely. With a weak password: yes.

**Strong password** (secure):
- 16+ characters
- Mixed case, numbers, symbols
- Random (use password manager)

**Weak password** (insecure):
- Dictionary words
- Short (<12 characters)
- Common patterns ("Password123!")

### How does it protect against tampering?

Uses authenticated encryption (AEAD). Any modification to the ciphertext causes decryption to fail with `ValueError`.

### What about quantum computers?

XChaCha20 and Argon2 are **not quantum-resistant**. If quantum computers become practical:
- 256-bit keys provide reduced security
- Argon2 remains partially resistant (memory-hard)

For quantum resistance, consider post-quantum algorithms (not yet implemented).

### Should I compress before encrypting?

You can, but:
- ✅ Pro: Smaller ciphertext
- ❌ Con: Potential information leakage (compression ratio reveals info)
- ❌ Con: Slightly slower

For most use cases, don't compress unless file size is critical.

## Technical Questions

### What format is the ciphertext?

**Text/Bytes**:
```
[Salt (16 bytes)][Nonce (24 bytes)][Ciphertext + Tag]
```

**Files**:
```
[Salt (16)][Nonce (24)][Size (8)][Chunks...]
```

Each chunk: `[Chunk Nonce (24)][Encrypted Data + Tag (16)]`

### Why XChaCha20-Poly1305 instead of AES-GCM?

- **Larger nonces**: 192-bit vs 96-bit (no collision risk)
- **Simpler**: No timing attack concerns
- **Faster**: On non-AES-NI hardware
- **Modern**: Designed with lessons from AES

Both are secure; XChaCha20 has some advantages.

### Why Argon2id instead of bcrypt/scrypt?

- **More secure**: Winner of Password Hashing Competition
- **Memory-hard**: Resistant to GPU/ASIC attacks
- **Configurable**: Can adjust security parameters
- **Modern**: Designed specifically for password hashing

### Can I change Argon2 parameters?

Not currently exposed in Python API. Default parameters (64 MiB, 3 iterations) balance security and performance.

To customize, fork and modify `src/crypto.rs`.

### Is the library thread-safe?

Yes. All functions are thread-safe and can be called from multiple threads.

### Does it zero memory after use?

Yes, for sensitive data like keys. Uses `zeroize` crate to securely clear memory.

## Error Handling

### What does "Authentication failed" mean?

Either:
1. **Wrong password** - most common
2. **Tampered data** - ciphertext was modified
3. **Corrupted file** - file damage

Always investigate authentication failures.

### Why does encryption/decryption fail?

Common causes:
- **Wrong password** (decryption)
- **File not found** (file operations)
- **Insufficient disk space** (file operations)
- **Permission denied** (file operations)
- **Corrupted input** (decryption)

Check error message and traceback.

### How do I handle errors properly?

```python
import irene_cipher

try:
    plaintext = irene_cipher.decrypt_text(ciphertext, password)
except ValueError as e:
    # Wrong password or tampered data
    print(f"Authentication failed: {e}")
except RuntimeError as e:
    # Other errors (I/O, etc.)
    print(f"Decryption error: {e}")
```

## Development Questions

### How do I build from source?

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install maturin
pip install maturin

# Build
git clone https://github.com/yourusername/irene-cipher
cd irene-cipher
maturin develop --release
```

### How do I contribute?

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### How do I report security issues?

**Do NOT open public issues.** Email security@example.com privately.

### Can I use this in commercial projects?

Yes! MIT license allows commercial use. See [LICENSE](LICENSE).

## Comparison Questions

### vs cryptography (Python library)?

- **Irene Cipher**: High-level, Pythonic, streaming files, Rust-based
- **cryptography**: Low-level, flexible, more algorithms, widely used

Use Irene Cipher for simple encryption. Use cryptography for complex crypto needs.

### vs PyCryptodome?

Similar comparison to cryptography. Irene Cipher is higher-level and more focused.

### vs NaCl/PyNaCl?

- **Similar**: Both use modern algorithms (ChaCha20)
- **Irene Cipher**: Password-based, streaming files, Python-focused
- **NaCl**: Key-based, simpler, more established

### vs AES encryption?

XChaCha20 is generally better:
- Simpler implementation
- No timing attack concerns
- Larger nonces
- Similar or better performance

Both are secure when used correctly.

## Troubleshooting

### Import error on Windows

Install Visual C++ Redistributable:
https://aka.ms/vs/17/release/vc_redist.x64.exe

### Build fails on macOS

Install Xcode Command Line Tools:
```bash
xcode-select --install
```

### Performance is slow

- **Key derivation** is intentionally slow (security feature)
- **Encryption** should be fast (~67 MB/s)
- If too slow, check:
  - Debug build vs release build
  - CPU performance
  - I/O bottlenecks

### Module not found

```bash
# Reinstall
pip uninstall irene-cipher
pip install irene-cipher

# Or build from source
maturin develop --release
```

---

Still have questions? Open a [Discussion](https://github.com/yourusername/irene-cipher/discussions) or [Issue](https://github.com/yourusername/irene-cipher/issues).
