hive_btle/security/
mod.rs

1// Copyright (c) 2025-2026 (r)evolve - Revolve Team LLC
2// SPDX-License-Identifier: Apache-2.0
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! Security module for HIVE-BTLE
17//!
18//! Provides two layers of encryption:
19//!
20//! ## Phase 1: Mesh-Wide Encryption
21//!
22//! All formation members share a secret and can encrypt/decrypt documents.
23//! Protects against external eavesdroppers.
24//!
25//! ```ignore
26//! use hive_btle::security::MeshEncryptionKey;
27//!
28//! let secret = [0x42u8; 32];
29//! let key = MeshEncryptionKey::from_shared_secret("DEMO", &secret);
30//! let encrypted = key.encrypt(b"document").unwrap();
31//! ```
32//!
33//! ## Phase 2: Per-Peer E2EE
34//!
35//! Two specific peers establish a unique session via X25519 key exchange.
36//! Only sender and recipient can decrypt - other mesh members cannot.
37//!
38//! ```ignore
39//! use hive_btle::security::PeerSessionManager;
40//! use hive_btle::NodeId;
41//!
42//! let mut alice = PeerSessionManager::new(NodeId::new(0x11111111));
43//! let mut bob = PeerSessionManager::new(NodeId::new(0x22222222));
44//!
45//! // Key exchange
46//! let alice_msg = alice.initiate_session(NodeId::new(0x22222222), now_ms);
47//! let (bob_response, _) = bob.handle_key_exchange(&alice_msg, now_ms).unwrap();
48//! alice.handle_key_exchange(&bob_response, now_ms).unwrap();
49//!
50//! // Now Alice and Bob can communicate securely
51//! let encrypted = alice.encrypt_for_peer(NodeId::new(0x22222222), b"secret", now_ms).unwrap();
52//! let decrypted = bob.decrypt_from_peer(&encrypted, now_ms).unwrap();
53//! ```
54//!
55//! ## Encryption Layers
56//!
57//! ```text
58//! ┌─────────────────────────────────────────────────────────────────┐
59//! │  Phase 1: Mesh-Wide (Formation Key)                             │
60//! │  ┌─────────────────────────────────────────────────────────┐    │
61//! │  │  All formation members can decrypt                       │    │
62//! │  │  Protects: External eavesdroppers                        │    │
63//! │  │  Overhead: 30 bytes                                      │    │
64//! │  └─────────────────────────────────────────────────────────┘    │
65//! │                                                                  │
66//! │  Phase 2: Per-Peer E2EE (Session Key)                           │
67//! │  ┌─────────────────────────────────────────────────────────┐    │
68//! │  │  Only sender + recipient can decrypt                     │    │
69//! │  │  Protects: Other mesh members, compromised relays        │    │
70//! │  │  Overhead: 44 bytes                                      │    │
71//! │  └─────────────────────────────────────────────────────────┘    │
72//! └─────────────────────────────────────────────────────────────────┘
73//! ```
74
75mod mesh_key;
76mod peer_key;
77mod peer_session;
78
79// Phase 1: Mesh-wide encryption
80pub use mesh_key::{EncryptedDocument, EncryptionError, MeshEncryptionKey};
81
82// Phase 2: Per-peer E2EE
83pub use peer_key::{
84    EphemeralKey, KeyExchangeMessage, PeerIdentityKey, PeerSessionKey, SharedSecret,
85};
86pub use peer_session::{
87    PeerEncryptedMessage, PeerSession, PeerSessionManager, SessionState, DEFAULT_MAX_SESSIONS,
88    DEFAULT_SESSION_TIMEOUT_MS,
89};
hive_btle/security/mod.rs

hive_btle/security/
mod.rs
