Mahmoud-Emad 6e5d9b35e8 feat: Update SAL Vault examples and documentation

- Renamed examples directory to `_archive` to reflect legacy status.
- Updated README.md to reflect current status of vault module,
  including migration from Sameh's implementation to Lee's.
- Temporarily disabled Rhai scripting integration for the vault.
- Added notes regarding current and future development steps.

2025-07-10 14:03:43 +03:00

2.8 KiB

Raw Blame History

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:

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

Encryption

The module provides functionality for encrypting data using ChaCha20Poly1305:

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

Decryption

The module provides functionality for decrypting data encrypted with ChaCha20Poly1305:

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

Password-Based Key Derivation

The module provides functionality for deriving encryption keys from passwords:

// 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

2.8 KiB Raw Blame History