# Hero Vault Symmetric Encryption Module

The Symmetric Encryption module provides functionality for symmetric encryption and decryption using the ChaCha20Poly1305 algorithm.

## Module Structure

The Symmetric Encryption module is organized into:

- `implementation.rs` - Core implementation of symmetric encryption functionality
- `mod.rs` - Module exports and public interface

## Key Features

### Key Generation

The module provides functionality for generating secure symmetric keys:

```rust
// Generate a new symmetric key
let key = generate_key()?;
```

### Encryption

The module provides functionality for encrypting data using ChaCha20Poly1305:

```rust
// Encrypt data
let encrypted = encrypt(&key, "This is a secret message")?;
```

### Decryption

The module provides functionality for decrypting data encrypted with ChaCha20Poly1305:

```rust
// Decrypt data
let decrypted = decrypt(&key, &encrypted)?;
```

### Password-Based Key Derivation

The module provides functionality for deriving encryption keys from passwords:

```rust
// Derive a key from a password
let key = derive_key_from_password(password, salt)?;
```

## Technical Details

### ChaCha20Poly1305

The module uses the ChaCha20Poly1305 authenticated encryption with associated data (AEAD) algorithm, which provides both confidentiality and integrity protection.

ChaCha20 is a stream cipher designed by Daniel J. Bernstein, which is combined with the Poly1305 message authentication code to provide authenticated encryption.

Key features of ChaCha20Poly1305:

- 256-bit key
- 96-bit nonce (used once)
- Authentication tag to verify integrity
- High performance on modern processors
- Resistance to timing attacks

### Key Derivation

For password-based encryption, the module uses the PBKDF2 (Password-Based Key Derivation Function 2) algorithm to derive encryption keys from passwords.

Key features of PBKDF2:

- Configurable iteration count to increase computational cost
- Salt to prevent rainbow table attacks
- Configurable output key length
- Uses HMAC-SHA256 as the underlying pseudorandom function

## Security Considerations

- Always use a unique key for each encryption operation
- Never reuse nonces with the same key
- Store keys securely
- Use strong passwords for password-based encryption
- Consider the security implications of storing encrypted data

## Error Handling

The module uses the `CryptoError` type for handling errors that can occur during symmetric encryption operations:

- `InvalidKeyLength` - Invalid key length
- `EncryptionFailed` - Encryption failed
- `DecryptionFailed` - Decryption failed

## Examples

For examples of how to use the Symmetric Encryption module, see the `examples/hero_vault` directory, particularly:

- `example.rhai` - Basic example demonstrating symmetric encryption
- `advanced_example.rhai` - Advanced example with error handling