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 genesis;
76mod identity;
77mod membership_token;
78mod mesh_key;
79mod peer_key;
80mod peer_session;
81mod persistence;
82mod registry;
83mod signed_payload;
84
85// Device identity and attestation
86pub use identity::{
87    node_id_from_public_key, verify_signature, DeviceIdentity, IdentityAttestation, IdentityError,
88};
89
90// TOFU Identity Registry
91pub use registry::{IdentityRecord, IdentityRegistry, RegistryResult};
92
93// Mesh genesis and credentials
94pub use genesis::{MembershipPolicy, MeshCredentials, MeshGenesis};
95
96// Membership tokens (tactical trust)
97pub use membership_token::{MembershipToken, MAX_CALLSIGN_LEN, MESH_ID_SIZE, TOKEN_WIRE_SIZE};
98
99// Phase 1: Mesh-wide encryption
100pub use mesh_key::{EncryptedDocument, EncryptionError, MeshEncryptionKey};
101
102// Phase 2: Per-peer E2EE
103pub use peer_key::{
104    EphemeralKey, KeyExchangeMessage, PeerIdentityKey, PeerSessionKey, SharedSecret,
105};
106pub use peer_session::{
107    PeerEncryptedMessage, PeerSession, PeerSessionManager, SessionState, DEFAULT_MAX_SESSIONS,
108    DEFAULT_SESSION_TIMEOUT_MS,
109};
110
111// Credential persistence
112pub use persistence::{
113    MemoryStorage, PersistedState, PersistenceError, SecureStorage, PERSISTED_STATE_VERSION,
114};
115
116// Signed payload utilities
117pub use signed_payload::{DecodedPayload, SignedPayload, MIN_WIRE_SIZE, SIGNATURE_SIZE};
hive_btle/security/mod.rs

hive_btle/security/
mod.rs
