You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cbcedc8
Browse filesBrowse the repository at this point in the historyBrowse files
- Version badge and install snippets 2.6.2 -> 2.7.0
- Add a Feature Maturity table marking post-quantum crypto, WebRTC
transport, session backup, connection pooling, and advanced key
rotation scheduling as stubs; the README previously listed them
alongside shipped features
- Add an "Upgrading to 2.7.0" section covering the breaking
password-key storage layout change, the KeyRotationStrategy.Standard
behavior change, and the additive PN wire-format field
- Rewrite the Security Features section to describe the actual
symmetric/DH ratchet split, replay-protection bounds, the X25519
small-order blacklist, and the per-key Argon2id salt
- Note out-of-order delivery support in the feature lists
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
[](https://buymeacoffee.com/russellbenzing)
11
11
12
12
**Secure end-to-end encryption for .NET — modern cryptographic protocols, production-ready**
@@ -27,7 +27,7 @@ A comprehensive, production-ready end-to-end encryption library for .NET applica
-**Perfect Forward Secrecy** - Past messages remain secure even if keys are compromised
520
-
-**Post-Compromise Security** - Future messages are secure after key compromise recovery
523
+
-**Symmetric Ratchet** - Every message key is derived, used once, then zeroed; used keys are never persisted
524
+
-**DH Ratchet** - A new Diffie-Hellman ratchet step runs on receipt of a peer's new ratchet key, giving post-compromise recovery
525
+
-**Perfect Forward Secrecy** - Past messages remain secure even if current keys are compromised
526
+
-**Post-Removal Forward Secrecy** - Group chain keys rotate immediately when a member is removed
527
+
528
+
> **On `KeyRotationStrategy.Standard`** (changed in v2.7): the DH ratchet advances only in response to
529
+
> a peer's new ratchet key, per the Signal specification. Earlier versions also rotated the sender's
530
+
> ratchet key every 20 messages; because a DH ratchet step is only valid once the peer holds the new
531
+
> public key, that could diverge both sides' DH inputs and permanently break a session where both
532
+
> parties were actively sending. Forward secrecy within a chain comes from the symmetric ratchet and
533
+
> is unaffected. `KeyRotationStrategy.AfterEveryMessage` is unchanged.
521
534
522
535
### Authentication & Integrity
523
536
524
-
-**Message Authentication** - Every message is cryptographically authenticated
525
-
-**Replay Protection** - Built-in protection against message replay attacks
526
-
-**Tampering Detection** - Immediate detection of message modification attempts
537
+
-**Message Authentication** - AES-256-GCM authenticates every message body
538
+
-**Replay Protection** - 500-entry FIFO deduplication in chat sessions, per-sender message IDs in groups
539
+
-**Tampering Detection** - Immediate detection of ciphertext modification
540
+
-**Key Validation** - X25519 public keys are checked against the full libsodium small-order point blacklist
527
541
528
542
### Memory Security
529
543
530
-
-**Secure Memory Handling** - Sensitive data is properly cleared from memory
531
-
-**Key Derivation** - HKDF for protocol keys; Argon2id (memory-hard, 64 MB) for password-based keys
544
+
-**Secure Memory Handling** - Key material is pinned and zeroed via `sodium_memzero`, including superseded root keys, chain keys, retired ratchet private keys, and evicted skipped-message keys
545
+
-**Key Derivation** - HKDF for protocol keys; Argon2id (memory-hard, 64 MB, per-key random salt) for password-based keys
532
546
-**Constant-Time Operations** - Protection against timing attacks
533
547
534
548
---
535
549
550
+
## 🧪 Feature Maturity
551
+
552
+
Not every type in the public surface is backed by a real implementation. This table is the
553
+
authoritative list — treat anything marked **Stub** as unavailable.
554
+
555
+
| Area | Status | Notes |
556
+
|------|--------|-------|
557
+
| X3DH + Double Ratchet | ✅ Production | Signal-compliant key agreement and ratcheting |
558
+
| AES-256-GCM / Ed25519 / X25519 | ✅ Production | All via libsodium |
559
+
| Chat & group sessions | ✅ Production | Replay protection, forward secrecy, member management |
560
+
| Multi-device linking & sync | ✅ Production | Encrypted persistent device list |
| Resilience (retry, circuit breaker, timeout) | ✅ Production |`ResilienceManager`|
564
+
|**Post-quantum crypto**| ⚠️ **Stub**|`PostQuantumCryptoStub` returns random bytes for all Kyber/Dilithium/Falcon operations and its `VerifyAsync` returns `true` for any correctly-sized signature. **Do not use for any security decision.**|
565
+
|**WebRTC transport**| ⚠️ **Stub**| Echoes sent bytes back as received |
566
+
|**Session backup manager**| ⚠️ **Stub**| Returns hardcoded checksums; writes nothing to disk |
567
+
|**Connection pool**| ⚠️ **Stub**| Returns a connection that echoes sends as receives |
568
+
|**Advanced key rotation scheduling**| ⚠️ **Stub**|`Task.Delay` then a synthetic result; no keys are rotated |
569
+
570
+
All stubs are targeted for real implementations in v3.0.
571
+
572
+
---
573
+
574
+
## ⬆️ Upgrading to 2.7.0
575
+
576
+
**Breaking — password-protected key storage.**`StoreKeyAsync()` / `RetrieveKeyAsync()` now derive
577
+
their encryption key with a fresh random Argon2id salt per stored key instead of a fixed
578
+
application-wide salt. The stored blob layout changed from `nonce‖ciphertext` to
579
+
`salt‖nonce‖ciphertext`, so **password-protected keys written by 2.6.x and earlier cannot be read by
580
+
2.7.0**. Re-store any affected keys before upgrading, or keep a 2.6.x reader available to migrate
581
+
them. Keys stored without a password are unaffected, as are session files and device lists.
582
+
583
+
**Behavioral — `KeyRotationStrategy.Standard`.** No longer performs a send-count-based DH ratchet
584
+
rotation; see [Forward Secrecy & Post-Compromise Security](#forward-secrecy--post-compromise-security).
585
+
No API change and no action required.
586
+
587
+
**Wire format — additive and backward compatible.**`EncryptedMessage` gained
588
+
`PreviousChainLength` (the Signal `PN` header field). It defaults to `0` when absent, so 2.7.0 reads
589
+
messages from older peers. Older peers ignore the field. Out-of-order delivery across a ratchet step
590
+
only recovers when *both* sides run 2.7.0+.
591
+
592
+
---
593
+
536
594
## 📦 Installation
537
595
538
596
### NuGet Package
539
597
540
598
```bash
541
-
dotnet add package LibEmiddle --version 2.6.2
599
+
dotnet add package LibEmiddle --version 2.7.0
542
600
```
543
601
544
602
### Package Manager Console
545
603
546
604
```powershell
547
-
Install-Package LibEmiddle -Version 2.6.2
605
+
Install-Package LibEmiddle -Version 2.7.0
548
606
```
549
607
550
608
### Requirements
@@ -568,7 +626,7 @@ Direct peer-to-peer encrypted communication using WebRTC data channels:
568
626
- Adaptive bitrate based on network conditions
569
627
- Network quality monitoring and automatic fallback
570
628
571
-
**Status**: Currently a stub implementation for API development. Not production-ready in v2.5.
629
+
**Status**: API stub only — `WebRTCTransportStub` echoes sent bytes back as received bytes. Not functional.
0 commit comments