139 lines
4.7 KiB
Markdown
139 lines
4.7 KiB
Markdown
# Vault Crate Overview
|
|
|
|
Welcome to the Vault crate! This document provides a high-level overview, usage examples, and a guide to the main components of the Vault system. For deeper technical details, see [`architecture.md`](architecture.md) and [`vault_impl_plan.md`](vault_impl_plan.md).
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
- [Summary](#summary)
|
|
- [Main Components](#main-components)
|
|
- [Security Model](#security-model)
|
|
- [Quickstart & Usage Examples](#quickstart--usage-examples)
|
|
- [More Information](#more-information)
|
|
|
|
---
|
|
|
|
## Summary
|
|
The Vault crate is a modular, async, and WASM-compatible cryptographic keystore. It manages encrypted keyspaces (each with multiple keypairs), provides cryptographic APIs, and persists all data via a pluggable key-value store. All sensitive material is always encrypted at rest.
|
|
|
|
---
|
|
|
|
## Main Components
|
|
- **VaultStore**: Central manager for all keyspaces. Handles creation, loading, and metadata.
|
|
- **KeySpace**: Isolated environment containing multiple keypairs, encrypted with its own password.
|
|
- **KeyPair**: Represents an individual cryptographic keypair (e.g., secp256k1, Ed25519).
|
|
- **Symmetric Encryption Module**: Handles encryption/decryption using ChaCha20Poly1305 and PBKDF2.
|
|
- **SessionManager** (optional): Manages active context for ergonomic API usage (not required for stateless usage).
|
|
|
|
---
|
|
|
|
## Security Model
|
|
- **Per-KeySpace Encryption:** Each keyspace is encrypted independently using a password-derived key.
|
|
- **VaultStore Metadata:** Stores non-sensitive metadata about keyspaces (names, creation dates, etc.).
|
|
- **Zero-Knowledge:** Passwords and keys are never stored in plaintext; all cryptographic operations are performed in memory.
|
|
|
|
---
|
|
|
|
## Quickstart & Usage Examples
|
|
|
|
```rust
|
|
// Create a new VaultStore
|
|
let mut vault = VaultStore::new();
|
|
|
|
// Create a new keyspace
|
|
vault.create_keyspace("personal", "password123")?;
|
|
|
|
// List available keyspaces
|
|
let keyspaces = vault.list_keyspaces();
|
|
|
|
// Unlock a keyspace
|
|
let keyspace = vault.load_keyspace("personal", "password123")?;
|
|
|
|
// Create a new keypair
|
|
let key_id = keyspace.create_key(KeyType::Secp256k1, "mykey")?;
|
|
|
|
// Sign a message
|
|
let signature = keyspace.sign(&key_id, b"hello world")?;
|
|
```
|
|
|
|
---
|
|
|
|
## More Information
|
|
- **Architecture & Design:** See [`architecture.md`](architecture.md)
|
|
- **Implementation Details:** See [`vault_impl_plan.md`](vault_impl_plan.md)
|
|
- **Build Instructions:** See [`build_instructions.md`](build_instructions.md)
|
|
|
|
---
|
|
|
|
*For advanced usage (stateless/session APIs, custom backends, WASM integration), see the linked documents above.*
|
|
}
|
|
|
|
### KeySpace API Example
|
|
|
|
```rust
|
|
impl KeySpace {
|
|
pub fn new(name: &str, password: &str) -> Result<Self, VaultError>;
|
|
pub fn save(&self) -> Result<(), VaultError>;
|
|
pub fn list_keypairs(&self) -> Vec<String>;
|
|
pub fn create_keypair(&mut self, name: &str) -> Result<(), VaultError>;
|
|
pub fn delete_keypair(&mut self, name: &str) -> Result<(), VaultError>;
|
|
pub fn rename_keypair(&mut self, old_name: &str, new_name: &str) -> Result<(), VaultError>;
|
|
pub fn get_keypair(&self, name: &str) -> Result<KeyPair, VaultError>;
|
|
pub fn sign(&self, keypair_name: &str, message: &[u8]) -> Result<Vec<u8>, VaultError>;
|
|
pub fn verify(&self, keypair_name: &str, message: &[u8], signature: &[u8]) -> Result<bool, VaultError>;
|
|
}
|
|
```
|
|
|
|
### KeyPair API Example
|
|
|
|
```rust
|
|
pub struct KeyPair {
|
|
// Internal fields
|
|
}
|
|
|
|
impl KeyPair {
|
|
pub fn new() -> Self;
|
|
pub fn from_private_key(private_key: &[u8]) -> Result<Self, VaultError>;
|
|
pub fn public_key(&self) -> Vec<u8>;
|
|
pub fn private_key(&self) -> Vec<u8>;
|
|
pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, VaultError>;
|
|
pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, VaultError>;
|
|
}
|
|
```
|
|
|
|
### SessionManager API Example (Optional)
|
|
|
|
```rust
|
|
pub struct SessionManager {
|
|
keyspace: KeySpace,
|
|
active_keypair: String,
|
|
}
|
|
|
|
impl SessionManager {
|
|
pub fn new(keyspace: KeySpace, keypair_name: &str) -> Result<Self, VaultError>;
|
|
pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, VaultError>;
|
|
pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, VaultError>;
|
|
pub fn switch_keypair(&mut self, keypair_name: &str) -> Result<(), VaultError>;
|
|
}
|
|
```
|
|
|
|
### Storage Structure
|
|
|
|
```text
|
|
vault_store/
|
|
├── metadata.json
|
|
└── keyspaces/
|
|
├── alice.ksp
|
|
├── bob.ksp
|
|
└── ...
|
|
```
|
|
- `metadata.json`: Contains metadata about each keyspace, such as name and creation date.
|
|
|
|
|
|
## Supported Environments
|
|
|
|
- **Native:** Uses filesystem or a database (e.g., SQLite) for storage.
|
|
- **Browser (WASM):** Uses IndexedDB or localStorage via the kvstore abstraction.
|
|
|
|
For full build and integration instructions, see [build_instructions.md](build_instructions.md).
|