Noise Protocol Framework

Relevant source files

• BRING_THE_NOISE.md
• bitchat/Identity/IdentityModels.swift
• bitchat/Identity/SecureIdentityStateManager.swift
• bitchat/Noise/NoiseProtocol.swift
• bitchat/Noise/NoiseRateLimiter.swift
• bitchat/Noise/NoiseSecurityConstants.swift
• bitchat/Noise/NoiseSecurityError.swift
• bitchat/Noise/NoiseSecurityValidator.swift
• bitchat/Noise/NoiseSession.swift
• bitchat/Noise/NoiseSessionManager.swift
• bitchat/Noise/SecureNoiseSession.swift
• bitchat/Services/KeychainManager.swift
• bitchat/Services/NoiseEncryptionService.swift
• bitchatTests/Noise/NoiseCoverageTests.swift
• bitchatTests/Noise/NoiseProtocolTests.swift

Purpose and Scope

This page documents BitChat's implementation of the Noise Protocol Framework, specifically the Noise_XX_25519_ChaChaPoly_SHA256 pattern used for Bluetooth mesh encryption. The implementation is found in bitchat/Noise/NoiseProtocol.swift1-123 and provides:

• Three-message XX handshake with mutual authentication bitchat/Noise/NoiseProtocol.swift38-45
• ChaCha20-Poly1305 AEAD transport encryption after handshake completion bitchat/Noise/NoiseProtocol.swift28-29
• Forward secrecy through ephemeral key mixing and immediate clearing of sensitive material bitchat/Noise/NoiseProtocol.swift34-35
• Replay protection via a sliding window nonce tracking algorithm bitchat/Noise/NoiseProtocol.swift52-57

Scope: This page covers the low-level Noise protocol primitives (NoiseCipherState, NoiseSymmetricState, NoiseHandshakeState) and the NoiseSession lifecycle. For high-level service integration, see page 4.2.

Core Classes:

Class	File Location	Purpose
NoiseCipherState	bitchat/Noise/NoiseProtocol.swift132-160	ChaCha20-Poly1305 encryption with nonce management and replay protection
NoiseSymmetricState	bitchat/Noise/NoiseProtocol.swift395-405	HKDF key derivation and transcript hashing
NoiseHandshakeState	bitchat/Noise/NoiseProtocol.swift522-540	XX pattern state machine and message processing
NoiseSession	bitchat/Noise/NoiseSession.swift14-46	Manages state and transitions for a specific peer connection
SecureNoiseSession	bitchat/Noise/SecureNoiseSession.swift11-15	Extends NoiseSession with security guardrails (timeouts, limits)

Sources: bitchat/Noise/NoiseProtocol.swift1-123 bitchat/Noise/NoiseSession.swift14-46 bitchat/Noise/SecureNoiseSession.swift11-15

---

Role in Dual Transport Architecture

BitChat utilizes the Noise Protocol specifically for its peer-to-peer Bluetooth mesh transport. While Nostr transport uses NIP-17/NIP-44, the BLE transport requires a stateful, mutually authenticated session to ensure privacy in local mesh environments.

Component Relationship Diagram

This diagram maps the natural language "Encryption Flow" to the specific code entities that handle each stage of the Noise lifecycle.

Diagram: Cryptographic Component Relationships

Sources: bitchat/Noise/NoiseProtocol.swift522-540 bitchat/Noise/NoiseSession.swift14-32 bitchat/Services/NoiseEncryptionService.swift149-173 bitchat/Noise/NoiseSessionManager.swift14-32 bitchat/Noise/SecureNoiseSession.swift11-15

---

Protocol Configuration

BitChat implements the Noise_XX_25519_ChaChaPoly_SHA256 configuration bitchat/Noise/NoiseProtocol.swift114-123:

Component	Implementation	Purpose
Pattern	XX	Mutual authentication; identities are encrypted bitchat/Noise/NoiseProtocol.swift93
DH Function	Curve25519	X25519 Elliptic Curve Diffie-Hellman bitchat/Noise/NoiseProtocol.swift116
Cipher	ChaChaPoly	ChaCha20-Poly1305 AEAD bitchat/Noise/NoiseProtocol.swift117
Hash	SHA256	SHA-256 for HKDF and transcript hashing bitchat/Noise/NoiseProtocol.swift118

XX Pattern Handshake Flow

The XX pattern consists of three messages bitchat/Noise/NoiseProtocol.swift38-45:

1. -> e: Initiator sends ephemeral public key.
2. <- e, ee, s, es: Responder sends ephemeral key, performs DH (ee), sends encrypted static key (s), performs DH (es).
3. -> s, se: Initiator sends encrypted static key (s), performs DH (se).

The NoiseSession class orchestrates these transitions, starting with startHandshake() bitchat/Noise/NoiseSession.swift50-77 and continuing with processHandshakeMessage(_:) bitchat/Noise/NoiseSession.swift79-153

Sources: bitchat/Noise/NoiseProtocol.swift25-45 bitchat/Noise/NoiseProtocol.swift114-123 bitchat/Noise/NoiseSession.swift50-153

---

Core Cryptographic Components

NoiseCipherState

The NoiseCipherState manages symmetric encryption and the sliding window replay protection bitchat/Noise/NoiseProtocol.swift132-151

• Nonce Management: Uses a UInt64 nonce bitchat/Noise/NoiseProtocol.swift139
• Replay Protection: Implements a 1024-message window bitchat/Noise/NoiseProtocol.swift135
• Safe Arithmetic: Uses overflow-safe checks in isValidNonce to prevent integer wrap-around vulnerabilities bitchat/Noise/NoiseProtocol.swift171-188

Diagram: NoiseCipherState Decryption Logic

Sources: bitchat/Noise/NoiseProtocol.swift132-145 bitchat/Noise/NoiseProtocol.swift171-188

NoiseSymmetricState

This class handles the evolution of the chainingKey and the hash (transcript) bitchat/Noise/NoiseProtocol.swift395-405 It provides mixKey for HKDF updates and split for generating final transport ciphers.

Sources: bitchat/Noise/NoiseProtocol.swift395-405

NoiseHandshakeState

Orchestrates the XX state machine bitchat/Noise/NoiseProtocol.swift522-540 It handles writeMessage and readMessage operations, processing tokens like e, s, ee, es, and se.

Sources: bitchat/Noise/NoiseProtocol.swift522-540

---

Identity Key Management

Static identity keys are generated as Curve25519.KeyAgreement.PrivateKey and stored securely.

• Storage: Keys are persisted in the iOS/macOS Keychain. The KeychainManager provides specific methods for saving and retrieving identity keys bitchat/Services/KeychainManager.swift90-100
• Initialization: NoiseSession is initialized with a localStaticKey bitchat/Noise/NoiseSession.swift38-44
• Fingerprinting: Peer identities are tracked through fingerprints derived from SHA256 of public keys bitchat/Services/NoiseEncryptionService.swift38
• Persistence Logic: The NoiseEncryptionService handles identity generation and loading via the KeychainManager, ensuring keys persist across app restarts bitchat/Services/NoiseEncryptionService.swift153-160

Sources: bitchat/Noise/NoiseSession.swift34-46 bitchat/Services/KeychainManager.swift90-100 bitchat/Services/NoiseEncryptionService.swift153-160

---

Session Management Lifecycle

Noise sessions are managed by NoiseSessionManager, which provides thread-safe access to peer sessions bitchat/Noise/NoiseSessionManager.swift14-18

Diagram: NoiseSession Handshake Exchange

Sources: bitchat/Noise/NoiseSession.swift50-153 bitchat/Noise/NoiseSessionManager.swift71-166

---

Security and Persistence

To maintain protocol integrity and protect against identity loss, BitChat integrates the Noise framework with secure identity state management.

• Identity Persistence: The SecureIdentityStateManager ensures that identity mappings (Ephemeral PeerID to Cryptographic Fingerprint) are encrypted at rest using AES-GCM and stored in the Keychain bitchat/Identity/SecureIdentityStateManager.swift32-36
• Keychain Reliability: KeychainManager implements a one-time upgrade of items to AfterFirstUnlock accessibility to ensure noise keys are readable while the device is locked bitchat/Services/KeychainManager.swift59-62
• Session Caching: Sessions are cached in memory by NoiseSessionManager for fast access bitchat/Noise/NoiseSessionManager.swift15
• Session Security: SecureNoiseSession adds security guardrails, including session timeouts and message count limits bitchat/Noise/SecureNoiseSession.swift16-54
• Rate Limiting: NoiseRateLimiter prevents DoS attacks by restricting handshake and message frequency per peer and globally bitchat/Noise/NoiseRateLimiter.swift13-21

Sources: bitchat/Identity/SecureIdentityStateManager.swift32-48 bitchat/Services/KeychainManager.swift59-62 bitchat/Noise/NoiseSessionManager.swift15 bitchat/Noise/SecureNoiseSession.swift16-54 bitchat/Noise/NoiseRateLimiter.swift13-21

---

Testing and Verification

The implementation is verified via the NoiseProtocolTests and NoiseCoverageTests suites.

• XX Pattern Handshake: Validates the 3-message exchange between aliceSession (initiator) and bobSession (responder) bitchatTests/Noise/NoiseProtocolTests.swift95-129
• Bidirectional Encryption: Verifies that messages can be encrypted and decrypted in both directions after the session is established bitchatTests/Noise/NoiseProtocolTests.swift163-177
• Replay Protection: NoiseCoverageTests specifically validates that NoiseCipherState rejects duplicate and stale nonces bitchatTests/Noise/NoiseCoverageTests.swift58-88
• Test Vectors: Support for official Noise test vectors ensures compatibility with the standard Noise_XX_25519_ChaChaPoly_SHA256 protocol bitchatTests/Noise/NoiseProtocolTests.swift17-37

Sources: bitchatTests/Noise/NoiseProtocolTests.swift95-177 bitchatTests/Noise/NoiseCoverageTests.swift58-88