ever-crypto 0.1.0

# Ever Crypto

A simple Rust library providing easy-to-use APIs for modern cryptographic operations, specifically:

- **XChaCha20Poly1305**: Authenticated encryption with extended nonce support
- **Kyber1024**: Post-quantum key encapsulation mechanism

## Features

- 🔒 **XChaCha20Poly1305** - Fast, secure authenticated encryption
- 🛡️ **Kyber1024** - Post-quantum cryptography ready
- 🚀 **Simple API** - Easy to use, hard to misuse
- 🔐 **Memory Safety** - Automatic secure memory cleanup with zeroization
- ✅ **Well Tested** - Comprehensive test suite

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
ever-crypto = "0.1.0"
```

## Usage Examples

### XChaCha20Poly1305 Encryption

```rust
use ever_crypto::{XChaChaCrypto, XChaChaKey, XChaChaNonce};

// Generate a key and nonce
let key = XChaChaKey::generate();
let nonce = XChaChaNonce::generate();

// Encrypt a message
let plaintext = b"Hello, World!";
let ciphertext = XChaChaCrypto::encrypt(&key, &nonce, plaintext, None).unwrap();

// Decrypt the message
let decrypted = XChaChaCrypto::decrypt(&key, &nonce, &ciphertext, None).unwrap();
assert_eq!(plaintext, &decrypted[..]);
```

### XChaCha20Poly1305 with Additional Authenticated Data (AAD)

```rust
use ever_crypto::{XChaChaCrypto, XChaChaKey};

let key = XChaChaKey::generate();
let plaintext = b"Secret message";
let aad = b"Additional authenticated data";

// Encrypt with random nonce
let (nonce, ciphertext) = XChaChaCrypto::encrypt_with_random_nonce(
    &key,
    plaintext,
    Some(aad),
).unwrap();

// Decrypt
let decrypted = XChaChaCrypto::decrypt(&key, &nonce, &ciphertext, Some(aad)).unwrap();
assert_eq!(plaintext, &decrypted[..]);
```

### Kyber1024 Key Encapsulation

```rust
use ever_crypto::{KyberCrypto, KyberKeyPair};

// Alice generates a key pair
let alice_keypair = KyberCrypto::generate_keypair();

// Bob encapsulates a shared secret for Alice
let (bob_shared_secret, ciphertext) = KyberCrypto::encapsulate(&alice_keypair.public_key);

// Alice decapsulates the shared secret
let alice_shared_secret = KyberCrypto::decapsulate(&ciphertext, &alice_keypair.secret_key);

// Both parties now have the same shared secret
assert_eq!(bob_shared_secret.as_bytes(), alice_shared_secret.as_bytes());
```

### Hybrid Encryption (Kyber1024 + XChaCha20Poly1305)

```rust
use ever_crypto::{KyberCrypto, XChaChaCrypto, XChaChaKey};

// Step 1: Key establishment with Kyber1024
let alice_keypair = KyberCrypto::generate_keypair();
let (shared_secret, kyber_ciphertext) = KyberCrypto::encapsulate(&alice_keypair.public_key);

// Step 2: Use shared secret as XChaCha20Poly1305 key
let xchacha_key = XChaChaKey::from_bytes(shared_secret.as_bytes()).unwrap();

// Step 3: Encrypt data with XChaCha20Poly1305
let plaintext = b"This is a secret message using hybrid encryption!";
let (nonce, ciphertext) = XChaChaCrypto::encrypt_with_random_nonce(
    &xchacha_key,
    plaintext,
    None,
).unwrap();

// Decryption process:
// Step 1: Alice decapsulates the shared secret
let alice_shared_secret = KyberCrypto::decapsulate(&kyber_ciphertext, &alice_keypair.secret_key);
let alice_xchacha_key = XChaChaKey::from_bytes(alice_shared_secret.as_bytes()).unwrap();

// Step 2: Decrypt the message
let decrypted = XChaChaCrypto::decrypt(&alice_xchacha_key, &nonce, &ciphertext, None).unwrap();
assert_eq!(plaintext, &decrypted[..]);
```

## API Reference

### XChaCha20Poly1305

#### Types
- `XChaChaKey`: 256-bit encryption key
- `XChaChaNonce`: 192-bit nonce (24 bytes)
- `XChaChaCrypto`: Main encryption/decryption operations

#### Methods
- `XChaChaKey::generate()`: Generate a random key
- `XChaChaKey::from_bytes(bytes)`: Create key from bytes
- `XChaChaNonce::generate()`: Generate a random nonce
- `XChaChaCrypto::encrypt(key, nonce, plaintext, aad)`: Encrypt data
- `XChaChaCrypto::decrypt(key, nonce, ciphertext, aad)`: Decrypt data
- `XChaChaCrypto::encrypt_with_random_nonce(key, plaintext, aad)`: Encrypt with auto-generated nonce

### Kyber1024

#### Types
- `KyberKeyPair`: Public and secret key pair
- `KyberPublicKey`: Public key for encapsulation
- `KyberSecretKey`: Secret key for decapsulation
- `KyberSharedSecret`: 32-byte shared secret
- `KyberCiphertext`: Encapsulated ciphertext

#### Methods
- `KyberCrypto::generate_keypair()`: Generate a new key pair
- `KyberCrypto::encapsulate(public_key)`: Encapsulate a shared secret
- `KyberCrypto::decapsulate(ciphertext, secret_key)`: Decapsulate shared secret
- `KyberCrypto::sizes()`: Get component sizes

## Key Sizes

| Component | Size (bytes) |
|-----------|--------------|
| XChaCha20Poly1305 Key | 32 |
| XChaCha20Poly1305 Nonce | 24 |
| Kyber1024 Public Key | 1,568 |
| Kyber1024 Secret Key | 3,168 |
| Kyber1024 Ciphertext | 1,568 |
| Kyber1024 Shared Secret | 32 |

## Security Notes

- XChaCha20Poly1305 provides authenticated encryption with 256-bit security
- Kyber1024 is designed to be secure against both classical and quantum attacks
- All secret keys are automatically zeroized when dropped
- Never reuse nonces with the same key in XChaCha20Poly1305
- The library uses cryptographically secure random number generation

## Testing

Run the test suite:

```bash
cargo test
```

For verbose output:

```bash
cargo test -- --nocapture
```

## Dependencies

- `chacha20poly1305`: Pure Rust implementation of XChaCha20Poly1305
- `pqcrypto-kyber`: Post-quantum cryptography (Kyber1024)
- `aead`: Authenticated encryption trait definitions
- `rand_core`: Random number generation
- `thiserror`: Error handling
- `zeroize`: Secure memory cleanup

## License

This project is licensed under the MIT License.