4.7 KiB
Executable File
Network Security
CBDDC v0.6.0 introduces optional secure networking to protect data in transit between peers using industry-standard cryptography.
Overview
The security layer provides:
- ECDH (Elliptic Curve Diffie-Hellman) key exchange for establishing shared secrets
- AES-256-CBC encryption for all synchronized data
- HMAC-SHA256 authentication to prevent tampering
- Perfect Forward Secrecy - each session uses unique ephemeral keys
When to Use Secure Networking
✅ Recommended For:
- Sensitive data (customer information, financial records, health data)
- Compliance requirements (GDPR, HIPAA, PCI-DSS)
- Untrusted network segments within your LAN
- Production deployments where data confidentiality is important
⚠️ Consider Performance Impact:
- Encryption adds ~5-10ms latency per message
- CPU overhead for encryption/decryption
- Not necessary for public/non-sensitive data
How It Works
Handshake Process
Peer A Peer B
| |
| 1. Generate ECDH keypair |
|------ Public Key A ---------------->| 2. Generate ECDH keypair
| |
|<----- Public Key B -----------------|
| |
3. Compute shared secret 3. Compute shared secret
4. Derive encryption keys 4. Derive encryption keys
| |
|==== Encrypted Communication ====|
Encryption Details
- Key Exchange: NIST P-256 elliptic curve (secp256r1)
- Encryption: AES-256 in CBC mode with random IV per message
- Authentication: HMAC-SHA256 over ciphertext
- Message Format:
IV (16 bytes) + Ciphertext + HMAC (32 bytes)
Usage
Enable Security
using CBDDC.Network.Security;
// Register secure handshake service
services.AddSingleton<IPeerHandshakeService, SecureHandshakeService>();
// Network will automatically use encryption if service is registered
services.AddCBDDCNetwork(nodeId, tcpPort, authToken);
Console Sample (--secure flag)
# Start with encryption enabled
dotnet run --secure
# Or without encryption (faster, less secure)
dotnet run
UI Clients
If you build a UI client, enable secure mode by default to avoid mixed-security clusters.
Verify Security Status
UI clients should display security status:
- 🔒 Encrypted - Secure communication active
- 🔓 Plaintext - No encryption (Console sample default)
Configuration
Optional: Custom Security Settings
Currently, security uses default secure parameters. Future versions may support:
- Custom curve selection
- Cipher suite configuration
- Certificate pinning
Security Considerations
✅ What This Protects Against:
- Eavesdropping: Data is encrypted in transit
- Tampering: HMAC prevents message modification
- Man-in-the-Middle: ECDH provides authenticity
⚠️ Out of Scope:
- Data at Rest: SQLite databases are NOT encrypted. Use OS-level encryption if needed.
- Authentication: No peer identity verification beyond shared auth token.
- Public Internet: Still designed for trusted LANs. Use VPN/firewall for internet exposure.
Performance Impact
Benchmarks on typical workloads:
| Operation | Plaintext | Encrypted | Overhead |
|---|---|---|---|
| Small sync (10 docs) | 15ms | 22ms | +47% |
| Large sync (1000 docs) | 450ms | 520ms | +16% |
| Handshake | N/A | 8ms | Initial |
Recommendation: Enable for production. Disable for development/testing if needed.
Compatibility
- Secure ↔ Secure: ✅ Works
- Plaintext ↔ Plaintext: ✅ Works
- Secure ↔ Plaintext: ❌ Connection fails (by design)
All nodes in a network must use the same security mode.
FAQ
Q: Can I use this over the public internet?
A: While encryption helps, CBDDC is still designed for LANs. Use VPN, firewall rules, and consider TLS/SSL wrapping for internet exposure.
Q: How do I encrypt the SQLite database?
A: Use SQLCipher or OS-level disk encryption (BitLocker, LUKS, FileVault).
Q: Can different nodes use different keys?
A: No. All nodes in a mesh share the same authToken. Key rotation is not yet supported.
Q: What about .NET Standard 2.0 support?
A: Security works on all target frameworks (netstandard2.0, net6.0, net8.0) with appropriate polyfills.
See Also: