View source on GitHub →

Security Follow-up Tasks

Completed Security Fixes (Session 2025-12-18)

✅ DID-TLS Binding Verification: Added explicit verification of DID-TLS binding during Hello message handling in icn-net/src/actor.rs. The server now verifies that the binding_info in the Hello message matches the peer's TLS certificate.

✅ Gateway Scope Validation: Added proper scope validation and authorization checks in icn-gateway/src/validation.rs and icn-gateway/src/api/auth.rs. Tokens can no longer request arbitrary scopes.

✅ Comprehensive Security Tests: Added extensive test coverage in:

  • icn-net/tests/client_cert_verification_integration.rs
  • icn-gateway/tests/scope_validation_integration.rs

Pending Security Enhancements

1. Full Mutual TLS with Client Certificates - TOFU Mode (In Progress)

Status Snapshot (2025-12-18): Implemented with Trust-on-First-Use (TOFU) semantics - functionally complete, tests need updating.

Architecture Decision - RESOLVED: ICN uses TOFU (Trust-on-First-Use) semantics:

  1. TLS layer: Accept all valid DID certificates (verify cryptographic validity only)
  2. Application layer: Gate operations based on trust scores
  3. Trust building: Allow trust to develop through gossip/attestations over time

This avoids the chicken-and-egg problem where you need trust to establish connections, but need connections to build trust.

Implementation Complete:

  • icn-net/src/tls.rs: DidCertificateVerifier with TOFU mode (min_trust_threshold = 0.0)
  • icn-net/src/session.rs: Server config with client cert verification + trust graph integration
  • icn-net/src/actor.rs: Passes min_trust_threshold from rate limit config to session manager
  • Default production threshold: 0.1 (require Known trust class)
  • Tests can override with 0.0 for TOFU mode

Test Status:

  • ✅ Contract deployment tests: Pass with TOFU mode (min_trust_threshold = 0.0)
  • ✅ Multi-node gossip tests: Pass with explicit trust setup
  • ❌ DID-TLS binding tests: Need updating to provide trust_graph (currently use None = dev mode)

Remaining Work:

  1. Update icn-net/tests/did_tls_binding_integration.rs to provide trust_graph with TOFU threshold
  2. Add trust graph setup helper for tests
  3. Document TOFU mode in architecture docs
  4. Add metrics for TLS handshake failures by trust score

Security Properties:

  • All TLS connections require valid Ed25519-signed certificates
  • DID-TLS binding verified during Hello message exchange
  • Trust scores gate sensitive operations (gossip topics, contract execution, etc.)
  • Production deployments can increase min_trust_threshold for stricter access control

2. Replay Protection Cleanup (Medium Priority)

Issue: The ReplayGuard uses Bloom filters that can saturate over long-running sessions, potentially causing false positives and DoS. The cleanup() method exists but isn't actively called.

Location: icn-net/src/replay_guard.rs

Recommendation: Implement periodic cleanup task in NetworkActor to prune old entries and rotate Bloom filters.

3. Rate Limiter Pre-Verification Check (Low Priority)

Issue: Rate limiter checks message.from before signature verification in actor.rs:1452. While not a critical vulnerability (unsigned messages are rejected later), it could allow minor resource exhaustion.

Recommendation: Move rate limit check after signature verification, or implement a two-tier rate limiter (loose pre-auth, strict post-auth).

Testing Strategy

When re-enabling client certificate verification:

  1. Start with simple two-node tests where both nodes explicitly trust each other
  2. Gradually add complexity (three nodes, partial trust, untrusted peers)
  3. Test connection resilience (reconnection after trust changes)
  4. Performance test: measure TLS handshake overhead with cert verification

Documentation Needs

  • Update docs/ARCHITECTURE.md with TLS security model
  • Add deployment guide for setting up trust relationships
  • Document the trust threshold semantics (0.0 = allow all authenticated, 0.5 = moderate trust, etc.)
  • Create troubleshooting guide for TLS handshake failures

Metrics to Add

  • icn_net_tls_handshake_duration_seconds: Histogram of TLS handshake times
  • icn_net_tls_cert_verification_failures_total: Counter of cert verification failures by reason
  • icn_net_client_cert_presented_total: Counter of successful client cert presentations

Related Issues

  • Sequence number persistence for replay protection (#TBD)
  • Trust graph persistence and synchronization (#TBD)
  • Gateway token scope allowlist configuration (#TBD)

Last Updated: 2025-12-18 Contributors: GitHub Copilot CLI Security Review

← Back to Docs