Appendix B: Implementation Notes
This section is under construction. Full details of all 19 bugs will be documented.
B.1 SimpleX-specific AES-GCM (16-byte IV)
SimpleX uses 16-byte IVs for AES-256-GCM instead of the standard 12 bytes. Most cryptographic libraries default to 12-byte IVs. Implementers MUST ensure their AES-GCM implementation supports non-standard IV sizes.
The 16-byte IV is processed internally by GCM using GHASH, which changes the computation compared to 12-byte IVs.
B.2 Custom XSalsa20 in cbEncrypt/cbDecrypt
SimpleX's cbEncrypt/cbDecrypt functions use XSalsa20-Poly1305 (NaCl crypto_box) but with a non-standard nonce handling: zeros are used instead of nonce prefixes in certain contexts.
B.3 Empty Salt in Chain KDF
The Chain KDF (for deriving message keys) uses an empty salt ("", zero-length), not 32 or 64 zero bytes. This is unusual for HKDF and was a source of bugs.
B.4 Contact Queue vs Reply Queue Key Differences
| Property | Contact Queue | Reply Queue |
|---|---|---|
| Layer 2 E2E | None (skip) | Fresh DH computation |
| Key source | Pre-shared from invitation | Ephemeral per-message |
| DH key in cmHeader | Not present | SPKI-encoded X25519 |
B.5 unPad Layer
Between crypto_box decryption and ClientMessage parsing, there is an unPad step:
- Read first 2 bytes as BE16 length
- Extract
lengthbytes as the actual content - Discard remaining padding bytes
B.6 Common Implementation Pitfalls
| # | Bug | Impact | Session |
|---|---|---|---|
| 17 | Using msgId instead of cmNonce for Layer 2 | Decryption failure | S17 |
| 18 | Including length prefix in AAD | Auth tag mismatch | S17 |
| — | Wrong IV order in Chain KDF output | Wrong message key | S19 |
| — | Missing HSalsa20 step in crypto_box | Key derivation failure | S14 |
| — | Debug tests with production state side effects | State corruption | Multiple |
Full list of all 19 bugs with before/after analysis will be added.
B.7 Library Requirements
| Requirement | Why |
|---|---|
| X448/Curve448 support | Double Ratchet DH operations |
| AES-GCM with 16-byte IV | Non-standard IV size in ratchet |
| HKDF-SHA512 | Key derivation (NOT SHA256) |
| NaCl crypto_box (XSalsa20-Poly1305) | Layers 2 and 3 encryption |
| Ed25519 | SMP command signing |
| Zstd decompression (optional) | Compressed messages |