Platform-agnostic cryptographic kernel for secure peer-to-peer communication.

securebit_core is a pure Rust crate that provides cryptographic primitives and protocol implementation for secure WebRTC-based peer-to-peer communication. It is designed to be the single source of truth for all security-critical operations, reusable across desktop, mobile, and headless deployments.

• ECDH Key Exchange (P-384): Ephemeral key exchange with perfect forward secrecy
• ECDSA Signatures (P-384): Cryptographic authentication of protocol messages
• HKDF Key Derivation (SHA-256): Deterministic key derivation from shared secrets
• AES-256-GCM Encryption: Authenticated encryption for message confidentiality and integrity
• HMAC-SHA-256: Message authentication codes for integrity verification
• SAS (Short Authentication String): MITM detection via DTLS fingerprint verification

• Protocol Version Enforcement: Strict validation of protocol version (v4.0)
• Message Structure Validation: All protocol messages are validated before processing
• State Machine Integrity: Connection state transitions are enforced
• Replay Protection: Sequence numbers prevent message replay attacks
• Metadata Protection: Message metadata (timestamps, IDs) are encrypted separately

• Zero Platform Dependencies: No Tauri, no UI frameworks, no OS-specific APIs
• Cross-Platform: Works on Windows, macOS, Linux, Android, iOS
• Headless Support: Can be used in CLI tools, daemons, and background services
• Thread-Safe: Uses Arc<Mutex<>> for thread-safe state management

• Public Core: All security-critical code is in this public repository
• Auditable: Designed for independent security review
• No Backdoors: Zero external network calls, zero file system access
• Deterministic: Same inputs produce the same security-relevant outputs

Add to your Cargo.toml:

[dependencies]
securebit_core = { path = "../core" }  # Local path
# Or from crates.io (when published):
# securebit_core = "0.1.0"

use securebit_core::Core;

// Create a new Core instance
let core = Core::new();

// Create a secure offer (for initiator)
let offer = core.create_secure_offer(Some(web_rtc_sdp))?;
println!("Offer: {}", offer);

// Join a connection (for responder)
let answer = core.join_secure_connection(offer_data, Some(web_rtc_answer_sdp))?;
println!("Answer: {}", answer);

// Handle answer (for initiator)
let result = core.handle_secure_answer(answer_data)?;

// Encrypt a message
let encrypted = core.encrypt_enhanced_message(
    "Hello, world!".to_string(),
    "msg-123".to_string(),
    1
)?;

// Decrypt a message
let decrypted = core.decrypt_enhanced_message(encrypted)?;

use securebit_core::Core;
use std::sync::Arc;
use tauri::{State, Manager};

#[tauri::command]
fn create_secure_offer(
    core: State<Arc<Core>>,
    offer_sdp: Option<String>
) -> Result<String, String> {
    core.create_secure_offer(offer_sdp)
}

use securebit_core::Core;

#[no_mangle]
pub extern "C" fn create_secure_offer_ffi(
    offer_sdp: *const c_char,
    output: *mut c_char,
    output_len: usize,
) -> i32 {
    // FFI wrapper implementation
}

securebit_core/
├── src/
│   ├── core.rs          # Main Core struct and public API
│   ├── crypto.rs        # Cryptographic utilities
│   ├── session.rs       # Session management (encryption/decryption)
│   ├── webrtc.rs        # WebRTC protocol (offer/answer/join)
│   ├── error.rs         # Error types
│   ├── logger.rs        # Optional logging trait
│   └── lib.rs           # Public API exports
├── SECURITY_MODEL.md    # Security guarantees and boundaries
├── THREAT_MODEL.md      # Threats mitigated and not mitigated
└── README.md            # This file

The core manages three types of state:

1. Crypto State: Key pairs, encryption keys
2. Offer State: ECDH secrets, session salts, DTLS fingerprints
3. Session Keys: Encryption keys, MAC keys, metadata keys

All state is thread-safe via Arc<Mutex<>> and is never persisted to disk.

• ✅ Cryptographic Security: ECDH, ECDSA, HKDF, AES-GCM, HMAC
• ✅ Protocol Security: Version enforcement, message validation, state machine
• ✅ Key Management: Ephemeral keys, secure derivation, key isolation
• ✅ SAS Security: Deterministic SAS computation for MITM detection
• ✅ Input Validation: Strict validation of all inputs

• ❌ Platform Security: Protection against compromised OS/hardware
• ❌ Network Security: Protection against network-level attacks
• ❌ UI Security: Protection against malicious UI code
• ❌ Application Logic: Protection against application-level vulnerabilities
• ❌ Side-Channel Attacks: Protection against timing/power/cache attacks

See SECURITY_MODEL.md for detailed security guarantees.

• ✅ MITM Attacks: ECDH key exchange, ECDSA signatures, SAS verification
• ✅ Eavesdropping: AES-256-GCM encryption with ephemeral keys
• ✅ Message Tampering: HMAC-SHA-256, AES-GCM authentication
• ✅ Replay Attacks: Sequence numbers, timestamp validation
• ✅ Perfect Forward Secrecy: Ephemeral ECDH keys
• ✅ Protocol Attacks: Version enforcement, message validation

• ❌ Compromised OS/Hardware: Platform-level attacks
• ❌ Malicious UI: UI-level attacks (XSS, spoofing, phishing)
• ❌ Side-Channel Attacks: Timing, power, cache attacks
• ❌ Memory Dump Attacks: Process memory extraction
• ❌ Denial of Service: Resource exhaustion, crashes

See THREAT_MODEL.md for detailed threat analysis.

• create_secure_offer(offer_sdp: Option<String>) -> Result<String, String>

  • Creates a secure offer for peer-to-peer connection initiation
  • Returns: Encrypted offer in SB1:gz: format

• join_secure_connection(offer_data: String, answer_sdp: Option<String>) -> Result<String, String>

  • Joins a connection by processing an offer and creating an answer
  • Returns: Encrypted answer in SB1:gz: format

• handle_secure_answer(answer_data: String) -> Result<String, String>

  • Handles an answer from the responder (for initiator)
  • Returns: Connection result with session keys established

• parse_secure_offer(offer_data: String) -> Result<String, String>

  • Parses an offer to extract SDP and metadata
  • Returns: JSON string with parsed offer data

• encrypt_enhanced_message(message: String, message_id: String, sequence_number: u64) -> Result<String, String>

  • Encrypts a message with AES-256-GCM and HMAC-SHA-256
  • Returns: JSON string with encrypted message data

• decrypt_enhanced_message(encrypted_message: String) -> Result<String, String>

  • Decrypts a message and verifies integrity
  • Returns: JSON string with decrypted message data

• generate_key_pair() -> Result<String, String>

  • Generates a new cryptographic key pair
  • Returns: Key ID

• encrypt_data(data: &str, key_id: &str) -> Result<String, String>

  • Encrypts data using a key pair
  • Returns: JSON string with encrypted data

• decrypt_data(encrypted_data: &str) -> Result<String, String>

  • Decrypts data using a key pair
  • Returns: Decrypted data string

• generate_secure_password(length: usize) -> Result<String, String>

  • Generates a cryptographically secure random password
  • Returns: Random password string

• p384: P-384 elliptic curve (ECDH, ECDSA)
• aes-gcm: AES-256-GCM authenticated encryption
• hkdf: HKDF key derivation (SHA-256)
• hmac: HMAC-SHA-256 message authentication
• sha2: SHA-256, SHA-384 hashing

• serde, serde_json: Serialization
• rand: Cryptographically secure random number generation
• base64: Base64 encoding/decoding
• hex: Hexadecimal encoding/decoding
• chrono: Timestamp handling
• uuid: UUID generation
• flate2: Compression (zlib)
• serde_cbor: CBOR serialization
• regex: Regular expressions

No platform-specific dependencies (no Tauri, no UI frameworks, no OS APIs).

This crate has been audited for public security review. See:

• SECURITY_MODEL.md - Security guarantees and boundaries
• THREAT_MODEL.md - Threat analysis

Audit Status: ✅ APPROVED FOR PUBLIC PUBLICATION

Code Quality: ✅ Zero warnings, zero errors, all tests passing

License: Apache-2.0

This is a security-critical crate. All contributions must:

1. Maintain platform independence (no platform-specific code)
2. Preserve security guarantees (no weakening of security)
3. Follow Rust security best practices (no unsafe, proper error handling)
4. Include tests for new functionality
5. Update documentation (README, SECURITY_MODEL, THREAT_MODEL)

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

SPDX-License-Identifier: Apache-2.0

• Built with Rust's excellent cryptographic ecosystem
• Designed for independent security review and white-label distribution
• Inspired by Signal Protocol and OTR (Off-the-Record) messaging

For security issues, please contact the maintainers directly or open an issue on the repository.

For general questions, please open an issue on the repository.

Version: 0.1.0
License: Apache-2.0
Last Updated: 2025-12-23