hive_btle/security/
mod.rs

1//! Security module for HIVE-BTLE
2//!
3//! Provides two layers of encryption:
4//!
5//! ## Phase 1: Mesh-Wide Encryption
6//!
7//! All formation members share a secret and can encrypt/decrypt documents.
8//! Protects against external eavesdroppers.
9//!
10//! ```ignore
11//! use hive_btle::security::MeshEncryptionKey;
12//!
13//! let secret = [0x42u8; 32];
14//! let key = MeshEncryptionKey::from_shared_secret("DEMO", &secret);
15//! let encrypted = key.encrypt(b"document").unwrap();
16//! ```
17//!
18//! ## Phase 2: Per-Peer E2EE
19//!
20//! Two specific peers establish a unique session via X25519 key exchange.
21//! Only sender and recipient can decrypt - other mesh members cannot.
22//!
23//! ```ignore
24//! use hive_btle::security::PeerSessionManager;
25//! use hive_btle::NodeId;
26//!
27//! let mut alice = PeerSessionManager::new(NodeId::new(0x11111111));
28//! let mut bob = PeerSessionManager::new(NodeId::new(0x22222222));
29//!
30//! // Key exchange
31//! let alice_msg = alice.initiate_session(NodeId::new(0x22222222), now_ms);
32//! let (bob_response, _) = bob.handle_key_exchange(&alice_msg, now_ms).unwrap();
33//! alice.handle_key_exchange(&bob_response, now_ms).unwrap();
34//!
35//! // Now Alice and Bob can communicate securely
36//! let encrypted = alice.encrypt_for_peer(NodeId::new(0x22222222), b"secret", now_ms).unwrap();
37//! let decrypted = bob.decrypt_from_peer(&encrypted, now_ms).unwrap();
38//! ```
39//!
40//! ## Encryption Layers
41//!
42//! ```text
43//! ┌─────────────────────────────────────────────────────────────────┐
44//! │  Phase 1: Mesh-Wide (Formation Key)                             │
45//! │  ┌─────────────────────────────────────────────────────────┐    │
46//! │  │  All formation members can decrypt                       │    │
47//! │  │  Protects: External eavesdroppers                        │    │
48//! │  │  Overhead: 30 bytes                                      │    │
49//! │  └─────────────────────────────────────────────────────────┘    │
50//! │                                                                  │
51//! │  Phase 2: Per-Peer E2EE (Session Key)                           │
52//! │  ┌─────────────────────────────────────────────────────────┐    │
53//! │  │  Only sender + recipient can decrypt                     │    │
54//! │  │  Protects: Other mesh members, compromised relays        │    │
55//! │  │  Overhead: 44 bytes                                      │    │
56//! │  └─────────────────────────────────────────────────────────┘    │
57//! └─────────────────────────────────────────────────────────────────┘
58//! ```
59
60mod mesh_key;
61mod peer_key;
62mod peer_session;
63
64// Phase 1: Mesh-wide encryption
65pub use mesh_key::{EncryptedDocument, EncryptionError, MeshEncryptionKey};
66
67// Phase 2: Per-peer E2EE
68pub use peer_key::{
69    EphemeralKey, KeyExchangeMessage, PeerIdentityKey, PeerSessionKey, SharedSecret,
70};
71pub use peer_session::{
72    PeerEncryptedMessage, PeerSession, PeerSessionManager, SessionState, DEFAULT_MAX_SESSIONS,
73    DEFAULT_SESSION_TIMEOUT_MS,
74};
hive_btle/security/mod.rs

hive_btle/security/
mod.rs
