ce727eb30d
Add canonical operations/security/access/feature docs and fix path integrity to improve onboarding and incident readiness.
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: