99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
# 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
|