docs/crypto.md

1# SophaxChat Cryptography
2
3SophaxChat implements the same cryptographic protocols as Signal, adapted for a fully serverless P2P mesh.
4
5## Key Material
6
7Each identity consists of two keypairs:
8
9| Key | Algorithm | Purpose |
10|-----|-----------|---------|
11| Identity signing key | Ed25519 | Signs all WireMessages |
12| Identity DH key | X25519 | X3DH + Sealed Sender ECDH |
13| Signed prekey | X25519 | X3DH |
14| One-time prekeys | X25519 | X3DH (consumed once) |
15
16All keys are stored in the iOS Keychain with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`. Never exported, never backed up.
17
18---
19
20## X3DH (Extended Triple Diffie-Hellman)
21
22Used to establish a shared secret between Alice and Bob without a server.
23
24**Alice (sender) computes:**
25```
26EK_A = random X25519 keypair
27
28DH1 = ECDH(IK_A,  SPK_B)   // Alice identity × Bob signed prekey
29DH2 = ECDH(EK_A,  IK_B)    // Alice ephemeral × Bob identity
30DH3 = ECDH(EK_A,  SPK_B)   // Alice ephemeral × Bob signed prekey
31DH4 = ECDH(EK_A,  OPK_B)   // Alice ephemeral × Bob one-time prekey (if available)
32
33masterSecret = HKDF-SHA256(0x00…(32B) || DH1 || DH2 || DH3 [|| DH4],
34                           salt=0x00…(32B),
35                           info="SophaxChat_X3DH_v1",
36                           len=64)
37
38rootKey        = masterSecret[0:32]
39chainKey       = masterSecret[32:64]
40```
41
42**Bob (receiver) computes the same DH values** using his private keys and Alice's public keys from `InitiateSessionMessage`. Both derive identical `rootKey` and `chainKey`.
43
44**Forward secrecy**: Alice's ephemeral key `EK_A` is discarded after use. If an attacker later compromises long-term keys, past sessions remain secure.
45
46---
47
48## Double Ratchet
49
50After X3DH, both parties run the Double Ratchet to derive per-message keys.
51
52### Ratchet Header (in every message)
53
54```json
55{
56  "dhPublicKey":          "<base64 X25519 32B>",
57  "previousChainLength":  0,
58  "messageNumber":        0
59}
60```
61
62### KDF Chains
63
64**Root ratchet** (on each DH ratchet step):
65```
66rootKey, chainKey = HKDF-SHA256(rootKey || ECDH(myDH, theirDH),
67                                info="SophaxChat_RootRatchet_v1",
68                                len=64)
69```
70
71**Sending/receiving chain** (on each message):
72```
73messageKey, nextChainKey = HKDF-SHA256(chainKey,
74                                       info="SophaxChat_ChainRatchet_v1",
75                                       len=64)
76```
77
78### Message Encryption
79
80```
81nonce = random 12 bytes
82ciphertext = ChaCha20-Poly1305(key=messageKey, nonce=nonce, plaintext=JSON(MessageContent))
83wire = nonce || ciphertext || tag(16B)
84```
85
86**Out-of-order delivery**: skipped message keys are cached (max 1000 per session) until the out-of-order message arrives.
87
88---
89
90## Group Messaging — Sender Keys (v2)
91
92Each group member maintains a KDF chain per sender.
93
94### Key Distribution
95
96When a member joins or after a membership change, the member sends a `senderKeyDistribution` message (encrypted via Double Ratchet) to all other members:
97
98```json
99{
100  "groupID":    "UUID",
101  "senderID":   "alice_peerID",
102  "chainKey":   "<base64 32B>",
103  "iteration":  0
104}
105```
106
107### Per-Message Key Derivation
108
109```
110message_key  = HKDF-SHA256(chain_key, info="SophaxChat_SenderKey_Message_v1", len=32)
111next_chain   = HKDF-SHA256(chain_key, info="SophaxChat_SenderKey_Chain_v1",   len=32)
112```
113
114Iteration counter is included in every `GroupWireMessage` so receivers can fast-forward their chain if they missed messages (up to ±100 iterations tolerance).
115
116### Group Message Encryption
117
118```
119nonce      = random 12 bytes
120ciphertext = ChaCha20-Poly1305(key=message_key, nonce=nonce, plaintext=messageBody.utf8)
121wire       = nonce || ciphertext || tag(16B)
122```
123
124### Key Rotation
125
126When a member leaves (`groupMemberLeft`), remaining members generate new chain keys and redistribute via `senderKeyDistribution`. The leaver cannot decrypt future messages.
127
128---
129
130## Sealed Sender
131
132Prevents relay nodes from learning who is messaging whom.
133
134```
135EK_s          = random X25519 keypair (ephemeral, per message)
136sharedSecret  = ECDH(EK_s.private, recipient.dhIdentityKeyPublic)
137sealingKey    = HKDF-SHA256(sharedSecret,
138                            info="SophaxChat_SealedSender_v1",
139                            len=32)
140nonce         = random 12 bytes
141ciphertext    = ChaCha20-Poly1305(sealingKey, nonce, JSON(innerWireMessage))
142```
143
144Wire payload: `ephemeralPublicKey(32B) || nonce(12B) || ciphertext || tag(16B)`.
145
146---
147
148## Tor v3 .onion Address Derivation
149
150The app derives a stable .onion hostname from the Ed25519 identity signing key (no separate Tor key needed):
151
152```
153pubkey    = ed25519_signing_key_public  // 32 bytes
154checksum  = SHA3-256(".onion checksum" || pubkey || 0x03)[0:2]
155address   = BASE32(pubkey || checksum || 0x03) + ".onion"
156```
157
158This is Tor v3 SPEC (proposal 224). The address is deterministic — same identity key always produces the same .onion address.
159
160---
161
162## Safety Number
163
164Used for out-of-band identity verification (equivalent to Signal's safety number):
165
166```
167safetyNumber = hex(SHA-256(mySigningKey || theirSigningKey || myDHKey || theirDHKey))
168               formatted as 12 groups of 5 digits
169```
170
171Displayed in `IdentityView` and as a QR code for scanning.
172
173---
174
175## Implementation Notes
176
177- All crypto uses Apple **CryptoKit** (iOS/macOS) — hardware-backed on devices with Secure Enclave.
178- **ChaCha20-Poly1305** is preferred over AES-GCM for its resistance to timing attacks and nonce-misuse.
179- Message keys are **erased from memory** immediately after use (Swift `withUnsafeMutableBytes` zero-fill).
180- Keychain items use `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` — keys cannot leave the device.