gaia-crypt 0.1.0

# gaia-crypt

A hybrid encryption library in Rust that provides secure RSA + AES-GCM encryption and decryption functionality.

## Overview

`gaia-crypt` implements a modern hybrid cryptographic system that combines:
- RSA encryption for secure key exchange
- AES-256-GCM for efficient data encryption with authentication

This approach leverages the strengths of both algorithms: RSA's security for key exchange and AES's performance for bulk data encryption.

## Features

- Hybrid encryption model (RSA + AES-GCM)
- Strong 2048-bit RSA key generation
- AES-256-GCM authenticated encryption
- PEM key format support
- Rust-native implementation with minimal dependencies
- Comprehensive error handling

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
gaia-crypt = "0.1.0"
```

## Usage Examples

### Generate a Key Pair

```rust
use gaia_crypt::generate_rsa_keypair;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (private_key, public_key) = generate_rsa_keypair()?;
    
    // Keys can be converted to PEM strings for storage/transmission
    let private_key_pem = private_key.to_pkcs1_pem()?;
    let public_key_pem = public_key.to_public_key_pem()?;
    
    println!("Generated RSA key pair successfully");
    
    Ok(())
}
```

### Encrypt and Decrypt Data

```rust
use gaia_crypt::{encrypt, decrypt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // In a real application, you would load these from secure storage
    let public_key_pem = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----";
    let private_key_pem = "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----";
    
    // Data to encrypt
    let data = b"This is a secret message";
    
    // Encrypt using the recipient's public key
    let encrypted_data = encrypt(public_key_pem, data)?;
    println!("Encrypted data size: {} bytes", encrypted_data.len());
    
    // Decrypt using the recipient's private key
    let decrypted_data = decrypt(private_key_pem, &encrypted_data)?;
    
    assert_eq!(data, &decrypted_data[..]);
    println!("Successfully decrypted: {}", String::from_utf8_lossy(&decrypted_data));
    
    Ok(())
}
```

## How It Works

1. **Encryption Process**:
   - A random AES-256 key is generated
   - The plaintext is encrypted using AES-GCM with this key
   - The AES key is encrypted using the recipient's RSA public key
   - The encrypted key, nonce, and ciphertext are bundled and serialized

2. **Decryption Process**:
   - The bundle is deserialized to extract components
   - The AES key is decrypted using the recipient's RSA private key
   - The ciphertext is decrypted using the recovered AES key and nonce

This approach securely encrypts data of arbitrary size while maintaining performance.

## Security Considerations

- Uses standard, well-vetted cryptographic algorithms
- RSA keys are 2048 bits (sufficient for most use cases)
- AES-GCM provides authenticated encryption
- Nonces are generated randomly for each encryption
- No padding oracle vulnerabilities (uses PKCS#1 v1.5 for RSA)