Module security 

Security module for HIVE-BTLE

Provides two layers of encryption:

Phase 1: Mesh-Wide Encryption

All formation members share a secret and can encrypt/decrypt documents. Protects against external eavesdroppers.

use hive_btle::security::MeshEncryptionKey;

let secret = [0x42u8; 32];
let key = MeshEncryptionKey::from_shared_secret("DEMO", &secret);
let encrypted = key.encrypt(b"document").unwrap();

Phase 2: Per-Peer E2EE

Two specific peers establish a unique session via X25519 key exchange. Only sender and recipient can decrypt - other mesh members cannot.

use hive_btle::security::PeerSessionManager;
use hive_btle::NodeId;

let mut alice = PeerSessionManager::new(NodeId::new(0x11111111));
let mut bob = PeerSessionManager::new(NodeId::new(0x22222222));

// Key exchange
let alice_msg = alice.initiate_session(NodeId::new(0x22222222), now_ms);
let (bob_response, _) = bob.handle_key_exchange(&alice_msg, now_ms).unwrap();
alice.handle_key_exchange(&bob_response, now_ms).unwrap();

// Now Alice and Bob can communicate securely
let encrypted = alice.encrypt_for_peer(NodeId::new(0x22222222), b"secret", now_ms).unwrap();
let decrypted = bob.decrypt_from_peer(&encrypted, now_ms).unwrap();

Encryption Layers

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Mesh-Wide (Formation Key)                             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  All formation members can decrypt                       │    │
│  │  Protects: External eavesdroppers                        │    │
│  │  Overhead: 30 bytes                                      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  Phase 2: Per-Peer E2EE (Session Key)                           │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Only sender + recipient can decrypt                     │    │
│  │  Protects: Other mesh members, compromised relays        │    │
│  │  Overhead: 44 bytes                                      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Structs

DecodedPayload

Decoded signed payload

DeviceIdentity

A device’s cryptographic identity

EncryptedDocument

An encrypted HIVE document

EphemeralKey

An ephemeral X25519 keypair for forward secrecy

IdentityAttestation

An identity attestation proving ownership of a node_id

IdentityRecord

Record of a known identity

IdentityRegistry

TOFU Identity Registry

KeyExchangeMessage

Key exchange message sent to initiate or respond to E2EE session

MembershipToken

A membership token binding a device to a callsign within a mesh

MemoryStorage

In-memory storage for testing.

MeshCredentials

Shareable mesh credentials (without creator’s private key)

MeshEncryptionKey

Mesh-wide encryption key for HIVE documents

MeshGenesis

Genesis event for creating a new mesh

PeerEncryptedMessage

An encrypted peer-to-peer message

PeerIdentityKey

A long-term X25519 keypair for peer identity

PeerSession

A per-peer E2EE session

PeerSessionKey

Session key for per-peer E2EE encryption

PeerSessionManager

Manager for all per-peer E2EE sessions

PersistedState

Complete persisted state for a HIVE node.

SharedSecret

Raw shared secret from X25519 key exchange

SignedPayload

Signed payload encoding and verification utilities

Enums

EncryptionError

Errors that can occur during encryption/decryption

IdentityError

Errors that can occur during identity operations

MembershipPolicy

Membership policy controlling how nodes can join the mesh

PersistenceError

Errors that can occur during persistence operations.

RegistryResult

Result of identity verification

SessionState

Session state in the E2EE handshake

Constants

DEFAULT_MAX_SESSIONS

Maximum number of concurrent peer sessions

DEFAULT_SESSION_TIMEOUT_MS

Default session timeout (30 minutes)

MAX_CALLSIGN_LEN

Maximum callsign length (null-padded in wire format)

MESH_ID_SIZE

Size of mesh_id in bytes (matches MeshGenesis 8-char hex = 4 bytes)

MIN_WIRE_SIZE

Minimum wire size: marker (1) + signature (64)

PERSISTED_STATE_VERSION

Current version of the persisted state format.

SIGNATURE_SIZE

Signature size in bytes (Ed25519)

TOKEN_WIRE_SIZE

Total wire size of a MembershipToken

Traits

SecureStorage

Platform-agnostic secure storage abstraction.

Functions

node_id_from_public_key

Derive NodeId from a public key

verify_signature

Verify a signature from a known public key