common/crypto/mod.rs
1//! Cryptographic primitives for JaxBucket
2//!
3//! This module provides the cryptographic foundation for JaxBucket's security model:
4//!
5//! - **Identity & Authentication**: Ed25519 keypairs for peer identity
6//! - **Encryption**: AES-256-GCM for content encryption with per-item secrets
7//! - **Key Sharing**: ECDH-based key sharing using X25519 curve conversion
8//!
9//! # Security Model
10//!
11//! ## Peer Identity
12//! Each peer has an Ed25519 keypair (`SecretKey`/`PublicKey`) that serves as their
13//! identity in the network. This same keypair is used for key sharing.
14//!
15//! ## Content Encryption
16//! Every encrypted item (nodes, data) has its own AES-256-GCM `Secret` key. This provides:
17//! - Content-addressed storage (hashes are stable)
18//! - Per-item encryption (no shared secrets across items)
19//! - Forward secrecy (rotating keys doesn't require re-encryption)
20//!
21//! ## Key Sharing Protocol
22//! To share a bucket with another peer:
23//! 1. Generate ephemeral Ed25519 keypair
24//! 2. Convert both peer's Ed25519 keys to X25519 (Montgomery curve)
25//! 3. Perform ECDH to derive shared secret
26//! 4. Use AES-KW (key wrap) to encrypt the bucket secret with shared secret
27//! 5. Package as a `Share` (ephemeral_pubkey || wrapped_secret)
28//!
29//! The recipient can recover the secret by:
30//! 1. Extracting the ephemeral public key from the Share
31//! 2. Converting keys to X25519
32//! 3. Performing ECDH with their private key
33//! 4. Using AES-KW to unwrap the secret
34
35mod keys;
36mod secret;
37mod share;
38
39pub use keys::{PublicKey, SecretKey};
40pub use secret::{Secret, SecretError};
41pub use share::{Share, ShareError};