6e5d9b35e8
- 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.
149 lines
4.0 KiB
Markdown
149 lines
4.0 KiB
Markdown
# SAL Vault
|
|
|
|
A secure, encrypted key-value store system for the System Abstraction Layer (SAL).
|
|
|
|
## Overview
|
|
|
|
SAL Vault provides a two-tiered encrypted storage system:
|
|
|
|
1. **Vault**: A collection of encrypted keyspaces
|
|
2. **KeySpace**: An individual encrypted key-value store within a vault
|
|
|
|
## Features
|
|
|
|
- **Secure Storage**: ChaCha20Poly1305 encryption for all data
|
|
- **Password-Based Encryption**: Keyspaces are encrypted using password-derived keys
|
|
- **Cross-Platform**: Works on both native and WASM targets
|
|
- **Async API**: Fully asynchronous operations
|
|
- **Type Safety**: Strong typing with comprehensive error handling
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Vault
|
|
├── KeySpace 1 (encrypted with password A)
|
|
├── KeySpace 2 (encrypted with password B)
|
|
└── KeySpace N (encrypted with password N)
|
|
```
|
|
|
|
Each keyspace is independently encrypted, allowing different access controls and security boundaries.
|
|
|
|
## Usage
|
|
|
|
### Creating a Vault
|
|
|
|
```rust
|
|
use sal_vault::{Vault, Error};
|
|
use std::path::Path;
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<(), Error> {
|
|
// Create a new vault at the specified path
|
|
let vault = Vault::new(Path::new("./my_vault")).await?;
|
|
|
|
// Open an encrypted keyspace
|
|
let keyspace = vault.open_keyspace("user_data", "secure_password").await?;
|
|
|
|
// Use the keyspace for encrypted storage
|
|
// (KeySpace API documentation coming soon)
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### WASM Support
|
|
|
|
The vault also supports WASM targets with browser-compatible storage:
|
|
|
|
```rust
|
|
#[cfg(target_arch = "wasm32")]
|
|
async fn wasm_example() -> Result<(), Error> {
|
|
let vault = Vault::new().await?; // No path needed for WASM
|
|
let keyspace = vault.open_keyspace("session_data", "password").await?;
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
## Security
|
|
|
|
### Encryption
|
|
|
|
- **Algorithm**: ChaCha20Poly1305 (AEAD)
|
|
- **Key Derivation**: PBKDF2 with secure parameters
|
|
- **Nonce Generation**: Cryptographically secure random nonces
|
|
- **Authentication**: Built-in authentication prevents tampering
|
|
|
|
### Best Practices
|
|
|
|
1. **Strong Passwords**: Use strong, unique passwords for each keyspace
|
|
2. **Secure Storage**: Store vault files in secure locations
|
|
3. **Access Control**: Limit filesystem access to vault directories
|
|
4. **Backup Strategy**: Implement secure backup procedures
|
|
5. **Key Rotation**: Periodically change keyspace passwords
|
|
|
|
## Error Handling
|
|
|
|
The vault uses a comprehensive error system:
|
|
|
|
```rust
|
|
use sal_vault::Error;
|
|
|
|
match vault.open_keyspace("test", "password").await {
|
|
Ok(keyspace) => {
|
|
// Success - use the keyspace
|
|
}
|
|
Err(Error::IOError(io_err)) => {
|
|
// Handle I/O errors (file system issues)
|
|
}
|
|
Err(Error::CryptoError(crypto_err)) => {
|
|
// Handle cryptographic errors (wrong password, corruption)
|
|
}
|
|
Err(other) => {
|
|
// Handle other errors
|
|
}
|
|
}
|
|
```
|
|
|
|
## Migration from Previous Implementation
|
|
|
|
This vault implementation replaces the previous Ethereum-focused vault. Key differences:
|
|
|
|
### What's New
|
|
- ✅ Simpler, more focused API
|
|
- ✅ Better cross-platform support
|
|
- ✅ Improved security model
|
|
- ✅ Cleaner error handling
|
|
|
|
### What's Changed
|
|
- ❌ No Ethereum wallet functionality
|
|
- ❌ No smart contract integration
|
|
- ❌ No built-in signing operations
|
|
- ⏳ Rhai scripting integration (coming soon)
|
|
|
|
### Archived Implementation
|
|
|
|
The previous implementation is preserved in `_archive/` for reference and potential feature extraction.
|
|
|
|
## Development Status
|
|
|
|
- ✅ **Core Vault**: Complete and functional
|
|
- ✅ **KeySpace Operations**: Basic implementation ready
|
|
- ✅ **Encryption**: Secure ChaCha20Poly1305 implementation
|
|
- ⏳ **Rhai Integration**: In development
|
|
- ⏳ **Extended API**: Additional convenience methods planned
|
|
- ⏳ **Documentation**: API docs being completed
|
|
|
|
## Contributing
|
|
|
|
When contributing to the vault module:
|
|
|
|
1. Maintain security-first approach
|
|
2. Ensure cross-platform compatibility
|
|
3. Add comprehensive tests for new features
|
|
4. Update documentation for API changes
|
|
5. Consider WASM compatibility for new features
|
|
|
|
## License
|
|
|
|
This module is part of the SAL project and follows the same licensing terms.
|