I built WG YubiKey Manager because I got tired of WireGuard configurations sitting in plaintext on my disk. Every security-conscious developer has that moment when they realize their VPN private keys are just files waiting to be stolen. This macOS app changes that by storing your WireGuard keys on YubiKey hardware where they belong.
The Problem: Keys on Disk
WireGuard is excellent, but its default approach puts private keys in configuration files on your drive. That’s a security risk I couldn’t ignore. Anyone with file system access—malware, physical access, cloud sync vulnerabilities—could extract these keys.
I needed something better. Hardware security keys like YubiKey exist precisely for this use case: storing cryptographic material where software can’t just grab it. The question was how to bridge WireGuard with YubiKey storage.
Architecture: Go + Svelte + YubiKey PIV
The solution combines several technologies into a cohesive desktop application. The backend runs on Go 1.25, handling YubiKey operations, WireGuard tunnel management, and system integration. The frontend uses Svelte 4 for the user interface, connected through Wails v2 framework.
YubiKey PIV slots store the actual WireGuard configurations. I use slots 5f0001 through 5f00ff, providing space for up to 255 VPN tunnels. Each configuration gets encrypted with GnuPG using AES-256 before storage, with your YubiKey PIN as the encryption passphrase.
Security Model: Zero Disk Exposure
Here’s how the security works: when you import a WireGuard configuration, the app encrypts it using GPG with AES-256 and stores the encrypted blob on your YubiKey. The private key never touches your disk in plaintext form.
At connection time, you enter your PIN, the app decrypts the configuration directly from the YubiKey into memory, extracts the private key, and passes it to WireGuard through stdin. The key exists in RAM only during the active session—no disk writes, no swap files, no persistence.
Key Features
The app provides one-click connect and disconnect functionality. Click a tunnel card, enter your PIN, and you’re connected. The menu bar shows your status—a filled circle when connected, empty when disconnected. Live statistics display handshake timing, transfer rates, latency, and peer information.
Configuration import supports both paste and file upload. The app validates WireGuard syntax before storage, catching configuration errors early. Multi-tunnel support means you can manage dozens of VPN configurations from a single interface.
Auto-discovery helps when moving between machines. Insert your YubiKey, click Sync, and the app scans all PIV slots to reconstruct your tunnel list. No manual reconfiguration needed—your VPN setups travel with your hardware key.
Technical Implementation
The privilege escalation system uses a one-time sudoers setup through macOS authorization dialogs. After initial setup, the app runs VPN operations passwordlessly using scoped sudo permissions. YubiKey operations run as your regular user account—no elevated privileges required.
The glassmorphism UI adapts to both light and dark themes, providing native macOS integration. The translucent window effects follow system appearance preferences automatically. Menu bar integration keeps the app accessible without cluttering your dock.
Threading handles real-time updates safely. Connection status, transfer statistics, and YubiKey presence get tracked through mutex-protected state management. The Svelte frontend receives updates through Wails event bindings, maintaining responsive UI during network operations.
Getting Started
Installation requires macOS 12.0+ and a YubiKey 5 series with PIV support. You’ll also need ykman, GnuPG, and WireGuard tools installed via Homebrew. The GitHub repository contains complete build instructions and dependency management.
After launching, the app prompts once for admin access to install sudoers rules. Insert your YubiKey, import your first configuration, and you’re ready. The app handles the cryptographic complexity—you just click connect.
For development, clone the repository and run wails dev for hot-reload development. Production builds use the included shell script to create a proper macOS application bundle ready for installation.
Why This Matters
Hardware-backed key storage isn’t just paranoia—it’s practical security. Your WireGuard keys represent network access, potentially to sensitive environments. Storing them on dedicated hardware adds a physical layer of protection that software alone cannot provide.
This approach also enables better operational security. Keys can’t leak through file synchronization, backup systems, or forensic disk analysis. Even with full system compromise, attackers need physical access to your YubiKey and knowledge of your PIN.
The MIT license keeps the project open for security auditing and community contributions. I built this for my own use, but the need for better VPN key management extends beyond personal projects. Security-conscious organizations can review, modify, and deploy this approach according to their requirements.
If you’re looking for strong security consulting or need help implementing custom solutions like this in your infrastructure, I provide IT consulting services and fractional CTO services to help organizations improve their security posture.
FAQ
Q: Does this work with other VPN protocols?
A: Currently, the app is WireGuard-specific. The architecture could be adapted for other protocols, but WireGuard’s simple key format makes it ideal for this approach.
Q: What happens if I lose my YubiKey?
A: Your configurations are only stored on the YubiKey. Keep backup copies of your WireGuard configurations separately, or consider using multiple YubiKeys for redundancy.
Q: Can I use this on Windows or Linux?
A: The current implementation is macOS-specific due to native menu bar integration and system authorization flows. The core concepts could be ported to other platforms.
Q: How secure is the PIN protection?
A: YubiKey PIV implements hardware-level PIN retry limits. After consecutive failed attempts, the device locks, requiring administrator reset. This provides strong protection against PIN brute force attacks.
Q: Does this support multiple YubiKeys?
A: The app works with one YubiKey at a time. Swapping keys requires manual sync operations to discover configurations. Future versions might support multiple device management.
Have questions about implementing similar security solutions? Share your feedback and let me know how you’re approaching VPN key management in your environment.
