herolib_rust/vault/src/symmetric

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