Cryptography deep dive
How Nudge protects your messages (and why it matters)
Nudge is built for high‑stakes communication: end‑to‑end encrypted messaging and calling, designed to remain secure even as adversaries and capabilities evolve. This page explains the cryptography at a detailed, technical level—including all cryptographic primitives, Swift packages, and how they work together.
Message content is encrypted on your device and only decrypted by intended recipients. Servers can relay data, but they cannot read it.
If a device key is compromised in the future, past messages remain protected because message keys continuously evolve.
After compromise, the protocol can "heal" as new secrets are introduced—limiting how long an attacker can keep reading traffic.
Swift Packages & Architecture
Nudge's cryptographic stack is built from several open-source Swift packages, each with a specific role in providing secure, post-quantum messaging.
PostQuantumSolace
github.com/needletails/post-quantum-solace
The high-level session management SDK that orchestrates all cryptographic operations. PostQuantumSolace provides the PQSSession API for creating sessions, sending messages, managing devices, and handling key rotation. It combines Double Ratchet protocol execution with post-quantum key exchange to deliver end-to-end encrypted messaging with forward secrecy and post-compromise security.
Dependencies: DoubleRatchetKit, NeedleTailLogger, NeedleTailAlgorithms
DoubleRatchetKit
github.com/needletails/double-ratchet-kit
Implements the Double Ratchet algorithm with Post-Quantum X3DH (PQXDH) integration. This package provides the core protocol for forward secrecy and post-compromise security. It handles the hybrid key exchange (Curve25519 + MLKEM1024), message key derivation, header encryption, and state management for secure messaging sessions. The DoubleRatchetStateManager actor manages ratchet state and provides thread-safe encryption/decryption operations.
Dependencies: NeedleTailCrypto, NeedleTailLogger, BinaryCodable
NeedleTailCrypto
github.com/needletails/needletail-crypto
A comprehensive cryptographic wrapper around Swift Crypto (swift-crypto) and CryptoKit. NeedleTailCrypto provides high-level APIs for key generation (Curve25519, P256, P384, P521, MLKEM1024), symmetric encryption/decryption (AES-GCM), key agreement (ECDH), key derivation (HKDF), and secure key storage via Keychain and Secure Enclave on Apple platforms. This package abstracts the low-level cryptographic operations and provides a consistent, production-ready interface.
Dependencies: swift-crypto (Apple), swift-collections
NeedleTailAlgorithms
github.com/needletails/needletail-algorithms
Provides algorithm implementations used throughout the cryptographic stack, including data structures and utilities for cryptographic operations. This package contains shared algorithmic components that are used by PostQuantumSolace and other NeedleTails packages.
NeedleTailLogger
github.com/needletails/needletail-logger
A logging framework used throughout the cryptographic stack for debugging, monitoring, and audit trails. Provides structured logging with configurable log levels and thread-safe logging operations.
BinaryCodable
github.com/needletails/binary-codable
Provides efficient binary encoding and decoding for cryptographic data structures. Used for serializing keys, messages, and protocol state in a compact, platform-independent format.
swift-crypto
github.com/apple/swift-crypto
Apple's cross-platform cryptographic library that provides the foundational cryptographic primitives. This package implements MLKEM1024 (Kyber), Curve25519, AES-GCM, SHA-256, SHA-512, HKDF, HMAC, and other standard algorithms. It's the low-level cryptographic engine that powers NeedleTailCrypto and the entire stack.
Cryptographic Primitives
Nudge uses a carefully selected set of cryptographic primitives, each chosen for specific security properties, performance characteristics, and resistance to both classical and quantum attacks.
MLKEM-1024 (Kyber-1024)
What it is: MLKEM-1024 is the NIST-standardized post-quantum key encapsulation mechanism (KEM) based on the Kyber algorithm. It's designed to resist attacks from both classical and quantum computers.
What it does: MLKEM-1024 enables two parties to establish a shared secret key over an insecure channel. One party generates a public/private key pair, and the other party uses the public key to encapsulate a shared secret. The private key holder can then decapsulate the secret. This provides security even against adversaries with quantum computers.
Why it matters: Classical key exchange algorithms (like RSA, ECC) will be broken by large-scale quantum computers. MLKEM-1024 provides "harvest now, decrypt later" protection—even if an attacker records encrypted traffic today, they cannot decrypt it in the future using quantum computers.
Implementation: Provided by swift-crypto (Apple), used in PQXDH handshake
Curve25519
What it is: Curve25519 is a high-performance elliptic curve designed for Elliptic Curve Diffie-Hellman (ECDH) key agreement. It provides 128 bits of security and is widely deployed in modern cryptographic systems.
What it does: Enables two parties to establish a shared secret by exchanging public keys. Each party combines their private key with the other's public key to derive the same shared secret. Curve25519 is used for both key agreement (ECDH) and digital signatures (Ed25519) in Nudge.
Why it matters: While not quantum-resistant, Curve25519 provides immediate security against classical attackers and is extremely fast. In Nudge's hybrid PQXDH design, Curve25519 provides security today while MLKEM-1024 provides security against future quantum threats. Both must be broken for an attacker to compromise the session.
Implementation: Provided by swift-crypto (Apple), used in PQXDH handshake and device key signing
HKDF (HMAC-based Key Derivation Function)
What it is: HKDF is a key derivation function that securely derives multiple keys from a single shared secret or high-entropy input. It uses HMAC (Hash-based Message Authentication Code) as its underlying primitive.
What it does: Takes a shared secret (from key exchange) and derives purpose-specific keys for encryption, authentication, and other uses. HKDF uses a salt (for domain separation) and optional context information to ensure different keys are derived for different purposes. Nudge uses HKDF with SHA-512 for deriving session keys from PQXDH shared secrets.
Why it matters: Key derivation prevents key reuse across different contexts, which is critical for security. Each derived key is cryptographically independent, so compromising one key doesn't affect others. HKDF is also used in the Double Ratchet protocol to derive message keys from chain keys.
Implementation: HKDF<SHA512> and HKDF<SHA256> from swift-crypto, used throughout the protocol
AES-GCM (Advanced Encryption Standard - Galois/Counter Mode)
What it is: AES-GCM is an authenticated encryption algorithm that provides both confidentiality (encryption) and integrity (authentication) in a single operation. It uses the AES block cipher in Galois/Counter Mode.
What it does: Encrypts message content and generates an authentication tag that proves the message hasn't been tampered with. AES-GCM is used to encrypt all message payloads in Nudge, ensuring that messages cannot be read or modified by attackers.
Why it matters: Authenticated encryption prevents both eavesdropping and tampering. If an attacker modifies an encrypted message, the authentication tag will be invalid and the decryption will fail. Nudge uses AES-256-GCM, providing 256 bits of security.
Implementation: Provided by swift-crypto (Apple), used for all message encryption via NeedleTailCrypto
SHA-256 & SHA-512 (Secure Hash Algorithms)
What it is: SHA-256 and SHA-512 are cryptographic hash functions that produce fixed-size outputs (256 and 512 bits respectively) from arbitrary inputs. They are one-way functions—easy to compute but computationally infeasible to reverse.
What it does: Used throughout the cryptographic stack for various purposes: SHA-256 is used in HMAC for chain key derivation in the Double Ratchet, SHA-512 is used in HKDF for session key derivation from PQXDH shared secrets, and both are used for integrity verification and key derivation.
Why it matters: Hash functions are fundamental building blocks. They ensure that keys are derived deterministically, that data integrity can be verified, and that cryptographic operations produce consistent results. SHA-512 provides additional security margin for key derivation operations.
Implementation: Provided by swift-crypto (Apple), used in HKDF, HMAC, and key derivation
HMAC (Hash-based Message Authentication Code)
What it is: HMAC is a message authentication code that uses a cryptographic hash function (like SHA-256) combined with a secret key to produce a tag that verifies both the authenticity and integrity of a message.
What it does: In Nudge, HMAC-SHA256 is used in the Double Ratchet protocol to derive chain keys and message keys. Each ratchet step uses HMAC to advance the key chain, ensuring that keys evolve deterministically and securely.
Why it matters: HMAC ensures that key derivation is secure and deterministic. It's used extensively in the Double Ratchet to provide forward secrecy—each message uses a unique key derived from the previous key, so compromising one key doesn't reveal past or future keys.
Implementation: HMAC<SHA256> from swift-crypto, used in Double Ratchet key derivation
How It All Works Together
1) Post‑quantum handshake (PQXDH)
When two users start a conversation, Nudge performs a hybrid key exchange:
- Curve25519 ECDH: Both parties exchange Curve25519 public keys and derive a shared secret using elliptic curve Diffie-Hellman
- MLKEM-1024 encapsulation: One party uses the other's MLKEM-1024 public key to encapsulate a shared secret
- Secret combination: The Curve25519 shared secret and MLKEM-1024 shared secret are concatenated
- HKDF derivation: HKDF-SHA512 derives the root key and initial chain keys from the combined secrets
This hybrid approach ensures security against both classical attackers (Curve25519) and quantum attackers (MLKEM-1024). Both must be broken to compromise the session.
2) Continuous key evolution (Double Ratchet)
After the handshake, the Double Ratchet protocol provides forward secrecy:
- Symmetric ratchet: Each message advances a chain key using HMAC-SHA256, deriving a unique message key
- Message encryption: The message key is used with AES-256-GCM to encrypt the message payload
- DH ratchet: Periodically, new Diffie-Hellman key exchanges update the root key and create new chain keys
- Key rotation: Old keys are discarded, ensuring forward secrecy—compromising current keys doesn't reveal past messages
The Double Ratchet ensures that each message uses a unique encryption key, and keys continuously evolve to provide post-compromise security.
What's encrypted (and what isn't)
Strong cryptography protects message content. Like all messaging systems, some network‑level metadata (e.g., IP routing) can still exist. Nudge's stack also supports metadata protection techniques such as encrypted headers to reduce traffic analysis signals.
- Encrypted: message contents, session secrets, sensitive metadata (where supported)
- Reduced exposure: counters/key identifiers via header encryption (where applicable)
- Still possible: transport‑level observations (timing, endpoints) depending on network conditions
Security Properties
Nudge's cryptographic design provides multiple layers of security:
- Post-quantum security: MLKEM-1024 protects against future quantum attacks
- Forward secrecy: Past messages remain secure even if current keys are compromised
- Post-compromise security: Sessions can recover from key compromise
- Authenticated encryption: AES-GCM prevents both eavesdropping and tampering
- Metadata protection: Header encryption reduces traffic analysis
Want a private Nudge community?
NeedleTails offers paid server implementation services for organizations that need private deployment, governance controls, and operational accountability.