Skip to content

Commit cbcedc8

Browse files
rbenzingclaude
andcommitted
docs: update README for v2.7.0
- 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>
1 parent 38acde5 commit cbcedc8

1 file changed

Lines changed: 74 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 74 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen?style=for-the-badge)]()
77
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg?style=for-the-badge)](./LICENSE)
88
[![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%2010.0-512BD4?style=for-the-badge&logo=dotnet&logoColor=white)](https://dotnet.microsoft.com/)
9-
[![Version](https://img.shields.io/badge/version-2.6.2-blue?style=for-the-badge)]()
9+
[![Version](https://img.shields.io/badge/version-2.7.0-blue?style=for-the-badge)]()
1010
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/russellbenzing)
1111

1212
**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
2727

2828
```csharp
2929
// Install via NuGet
30-
// dotnet add package LibEmiddle --version 2.6.2
30+
// dotnet add package LibEmiddle --version 2.7.0
3131
3232
using LibEmiddle.API;
3333
using LibEmiddle.Domain.Enums;
@@ -60,10 +60,11 @@ var encryptedMessage = await chatSession.EncryptAsync("Hello, secure world!");
6060
- **Double Ratchet Algorithm** - Continuous key rotation for forward secrecy
6161
- **AES-GCM Encryption** - Authenticated encryption with strong integrity guarantees
6262
- **Ed25519 & X25519** - Modern elliptic curve cryptography for digital signatures and key exchange
63-
- **Post-Quantum Cryptography** - Preparation for quantum-resistant algorithms (v2.5)
63+
- **Post-Quantum Cryptography** - API scaffolding only; see [Future Roadmap](#-future-roadmap) before use
6464
- **Advanced Key Rotation** - Sophisticated key rotation policies and monitoring
6565
- **Replay Attack Protection** - Per-sender message ID deduplication in both chat and group sessions
6666
- **Post-Removal Forward Secrecy** - Group chain key rotated immediately on member removal
67+
- **Out-of-Order Delivery** - Signal `PN` header field lets messages that arrive across a ratchet step still decrypt (v2.7)
6768

6869
### 💬 Communication Patterns
6970

@@ -73,6 +74,7 @@ var encryptedMessage = await chatSession.EncryptAsync("Hello, secure world!");
7374
- **Asynchronous Communication** - Robust mailbox system with delivery and read receipts
7475
- **Message Batching** - Efficient bulk messaging with compression support (v2.5)
7576
- **Flexible Transport Layer** - HTTP and InMemory transports (WebRTC planned for v3.0)
77+
- **Out-of-Order Tolerance** - Skipped message keys are retained across DH ratchet steps, so delayed or reordered messages still decrypt
7678

7779
### 🏗️ Architecture Highlights
7880

@@ -82,8 +84,11 @@ var encryptedMessage = await chatSession.EncryptAsync("Hello, secure world!");
8284
- **Structured Exceptions** - `LibEmiddleException` with typed `LibEmiddleErrorCode` for precise error handling
8385
- **Event-Driven** - Real-time message handling with comprehensive events
8486
- **Feature Flags** - Gradual rollout and configuration of new capabilities (v2.5)
85-
- **Enterprise Monitoring** - Built-in diagnostics and resilience management (v2.5)
86-
- **Connection Pooling** - Optimized connection management for high throughput (v2.5)
87+
- **Enterprise Monitoring** - Built-in diagnostics, plus retry / circuit-breaker / timeout via `ResilienceManager`
88+
89+
> **Note**: connection pooling, session backup, advanced key-rotation scheduling, WebRTC transport, and
90+
> post-quantum crypto are present as **API stubs only** — they satisfy their interfaces but perform no
91+
> real work. See [Feature Maturity](#-feature-maturity) before depending on them.
8792
8893
---
8994

@@ -515,36 +520,89 @@ client.KeyRotated += (sender, args) =>
515520

516521
### Forward Secrecy & Post-Compromise Security
517522

518-
- **Automatic Key Rotation** - Configurable rotation strategies
519-
- **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.
521534
522535
### Authentication & Integrity
523536

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
527541

528542
### Memory Security
529543

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
532546
- **Constant-Time Operations** - Protection against timing attacks
533547

534548
---
535549

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 |
561+
| Session persistence | ✅ Production | Argon2id-derived keys, atomic writes |
562+
| HTTP / InMemory transport | ✅ Production | |
563+
| 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+
536594
## 📦 Installation
537595

538596
### NuGet Package
539597

540598
```bash
541-
dotnet add package LibEmiddle --version 2.6.2
599+
dotnet add package LibEmiddle --version 2.7.0
542600
```
543601

544602
### Package Manager Console
545603

546604
```powershell
547-
Install-Package LibEmiddle -Version 2.6.2
605+
Install-Package LibEmiddle -Version 2.7.0
548606
```
549607

550608
### Requirements
@@ -568,7 +626,7 @@ Direct peer-to-peer encrypted communication using WebRTC data channels:
568626
- Adaptive bitrate based on network conditions
569627
- Network quality monitoring and automatic fallback
570628

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.
572630

573631
**Target**: v3.0 release
574632

0 commit comments

Comments
 (0)