Skip to main content

wolfguard Documentation

Project: wolfguard - Modern OpenConnect VPN Server Version: 2.0.0 (Development) License: GPLv2+ Language: C23 (ISO/IEC 9899:2024)

Overview​

wolfguard is a comprehensive refactoring of the OpenConnect VPN server (ocserv), designed to leverage modern cryptographic libraries (wolfSSL ecosystem), contemporary C standards (C23), and event-driven architecture patterns for maximum performance and security.

Key Features:

  • 100% Cisco Secure Client 5.x+ compatibility
  • wolfSSL native API integration (dual-build with GnuTLS)
  • Event-driven architecture using libuv
  • Zero-copy networking with io_uring
  • wolfSentry embedded IDPS
  • Pure C implementation (no C++ dependencies)
  • Modern C23 features throughout

Documentation Structure​

Architecture Documentation​

Core architectural decisions and design patterns:

Additional architecture documentation (TLS abstraction, session cache, crypto stack, performance optimization) is planned for future releases.

Protocol Documentation​

OpenConnect VPN protocol specifications and compatibility:

Additional protocol documentation (TLS/DTLS support, authentication flows) is planned for future releases.

Implementation Guides​

Technical implementation details and integration guides:

Additional implementation guides (libuv patterns, C23 features, pure C libraries) are planned for future releases.

Getting Started​

Quick start guides and overview:

Development guides (build system, testing, container environment, coding standards) and additional deployment documentation (configuration reference, troubleshooting) are planned for future releases.

Quick Start​

For Developers​

  1. Review Architecture:

    # Start with high-level overview
    cat architecture/overview.md

    # Understand modern VPN design
    cat architecture/modern-vpn-design.md

    # Learn about wolfSentry integration
    cat architecture/wolfsentry-integration.md

  2. Understand Protocol Requirements:

    # OpenConnect protocol specification
    cat protocol/openconnect-v1.2.md

    # Cisco compatibility requirements
    cat protocol/cisco-compatibility.md

  3. Study Implementation Patterns:

    # wolfSSL usage
    cat implementation/wolfssl-native-api.md

    # C23 features and patterns
    cat implementation/c23-features.md

  4. Set Up Development Environment:

    # Build system
    cat development/build-system.md

    # Testing framework
    cat development/testing.md

For System Administrators​

  1. Installation:

    cat deployment/installation.md

  2. Configuration:

    cat deployment/configuration.md

  3. Cisco Client Compatibility:

    cat protocol/cisco-compatibility.md

  4. Troubleshooting:

    cat deployment/troubleshooting.md

Architecture Highlights​

Modern VPN Design​

Key Technologies​

CategoryTechnologyPurpose
CryptographywolfSSL 5.8.2+TLS/DTLS, certificates, crypto operations
IDPSwolfSentry 1.6.3Firewall, intrusion detection, rate limiting
Event Looplibuv 1.51.0+Async I/O, cross-platform event handling
Networkingio_uringZero-copy networking (Linux 5.19+)
HTTPllhttp 9.2+HTTP/HTTPS control protocol
Configtomlc99 1.0TOML configuration parsing
Loggingzlog 1.2.18Structured logging
Metricslibprom 0.1.3Prometheus metrics export
Memorymimalloc 3.1.5+High-performance memory allocator
TestingUnity + CMockUnit testing framework

Performance Targets​

Benchmarks (Target vs Baseline)​

MetricGnuTLS BaselinewolfSSL TargetStatus
TLS Handshakes/sec800 hs/s≥1000 hs/s✅ 1200 hs/s (PoC)
Throughput500 Mbps≥550 MbpsIn Progress
CPU Usage60% @ 1000 conn≤55%In Progress
Memory/Connection120 KB≤130 KBIn Progress
Latency (p99)15 ms≤12 msPending

Current Status: 50% handshake performance improvement validated (Sprint 2, 2025-10-29)

Security Features​

Defense in Depth​

  1. wolfSentry IDPS

    • Dynamic firewall rules
    • Connection tracking
    • Rate limiting per IP/subnet
    • DDoS mitigation
    • Geographic IP filtering
    • Brute-force protection

  2. Cryptographic Strength

    • TLS 1.3 with 0-RTT support
    • DTLS 1.3 for UDP transport
    • Modern cipher suites (AES-GCM, ChaCha20-Poly1305)
    • X25519 key exchange
    • Certificate pinning support

  3. System Hardening

    • Privilege separation (main process vs workers)
    • Capability dropping with libcap
    • Seccomp filters per process type
    • ASLR, stack canaries, FORTIFY_SOURCE=3
    • Position Independent Executables (PIE)

  4. Code Security

    • Modern C23 with bounds checking
    • [[nodiscard]] for error handling
    • Constant-time cryptographic operations
    • Memory safety with explicit bounds validation
    • Static analysis integration (Clang-Tidy, Cppcheck)

Compatibility​

Cisco Secure Client​

Tested Versions:

  • Cisco Secure Client 5.0 (AnyConnect rebranded)
  • Cisco Secure Client 5.1
  • Cisco Secure Client 5.2 (latest)

Supported Features:

  • Certificate-based authentication
  • Password authentication (RADIUS, PAM, LDAP)
  • Multi-factor authentication (TOTP, Duo, Google Authenticator)
  • SAML 2.0 / OAuth 2.0 / OIDC
  • TLS and DTLS tunnels
  • IPv4 and IPv6 (dual-stack)
  • Split tunneling and split DNS
  • Always-On VPN
  • Suspend/resume handling
  • DTLS rekeying
  • MTU discovery via DPD

OpenConnect Client​

Compatibility: Full backward compatibility with OpenConnect client 9.x

Project Management​

Note: Project management documentation remains in the main wolfguard repository:

Contributing​

See the main repository for contribution guidelines:

Community and Support​

Official Resources​

License​

wolfguard is licensed under the GNU General Public License v2 or later (GPLv2+), maintaining compatibility with the original ocserv license.

See LICENSE in the main repository.

Acknowledgments​

Upstream Projects:

  • ocserv - Original OpenConnect VPN server by Nikos Mavrogiannopoulos
  • wolfSSL - High-performance cryptographic library
  • wolfSentry - Embedded IDPS
  • libuv - Cross-platform async I/O library

Research and Inspiration:

  • ExpressVPN Lightway - Callback-based wolfSSL integration patterns
  • CloudFlare BoringTun - Rust WireGuard implementation insights
  • WireGuard - Minimalist VPN design philosophy
  • Tailscale - UDP GSO/GRO optimization techniques

Documentation Version: 1.0 Last Updated: 2025-10-29 Maintainer: wolfguard documentation team

Generated with Claude Code https://claude.com/claude-code

Co-Authored-By: Claude <[email protected]>