wireguard

WireGuard

A Go implementation of WireGuard protocol for programmatic VPN connections.

Overview

This library provides a pure Go implementation of the WireGuard protocol, allowing you to create and manage WireGuard VPN connections programmatically. It's designed for applications that need to establish WireGuard tunnels without relying on external WireGuard tools or kernel modules.

Features

• Pure Go Implementation: No external dependencies on WireGuard tools
• Multiple Peers: Support for multiple peers with flexible routing
• Custom Dialer: net.Dialer-compatible interface for routing connections through WireGuard
• Configuration Files: Parse and generate standard WireGuard configuration files
• Flexible Routing: Support for specific subnets or full internet routing (0.0.0.0/0)
• HTTP Client Integration: Easy integration with Go's http.Client

Installation

go get github.com/hydrz/wireguard

Requirements

• Go 1.25.5 or later

Quick Start

package main

import (
    "log"
    "github.com/hydrz/wireguard"
)

func main() {
    // Generate private key
    privateKey, err := wireguard.GeneratePrivateKey()
    if err != nil {
        log.Fatal(err)
    }

    // Create device
    device, err := wireguard.NewDevice(privateKey)
    if err != nil {
        log.Fatal(err)
    }
    defer device.Close()

    // Bind to port
    if err := device.Bind(":51820"); err != nil {
        log.Fatal(err)
    }

    // Add a peer (use the peer's actual public key in production)
    peerPublicKey, _ := wireguard.ParsePublicKey("xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=")
    peer, err := device.AddPeer(
        peerPublicKey,
        wireguard.NoiseSymmetricKey{}, // No preshared key
        "vpn.example.com:51820",
        []string{"10.0.0.2/32"},
    )
    if err != nil {
        log.Fatal(err)
    }

    // Start device
    if err := device.Start(); err != nil {
        log.Fatal(err)
    }

    log.Printf("Device started with public key: %s", 
        wireguard.EncodePublicKey(device.PublicKey()))
}

Usage Examples

Using the Dialer for HTTP Requests

Route HTTP requests through a WireGuard tunnel:

import (
    "context"
    "net/http"
    "time"
    "github.com/hydrz/wireguard"
)

// Note: Error handling omitted for brevity. Always handle errors in production.

// Create device and add peer with full internet routing
privateKey, _ := wireguard.GeneratePrivateKey()
device, _ := wireguard.NewDevice(privateKey)
defer device.Close()

device.Bind(":51820")
device.Start()

// Use the actual peer's public key in production
peerPublicKey, _ := wireguard.ParsePublicKey("xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=")
peer, _ := device.AddPeer(
    peerPublicKey,
    wireguard.NoiseSymmetricKey{},
    "vpn.example.com:51820",
    []string{"0.0.0.0/0"}, // Route all traffic through this peer
)

// Create HTTP client with WireGuard dialer
dialer := wireguard.NewDialer(device, peer)
httpClient := &http.Client{
    Transport: &http.Transport{
        DialContext: dialer.DialContext,
    },
    Timeout: 30 * time.Second,
}

// Make requests - they will go through the WireGuard tunnel
resp, err := httpClient.Get("http://api.ipify.org")

Multiple Exit Nodes

Use multiple peers with 0.0.0.0/0 routing and choose which one to use:

import (
    "context"
    "github.com/hydrz/wireguard"
)

// Note: Error handling omitted for brevity. Always handle errors in production.

// Add multiple exit nodes with their actual public keys
exitNodes := []struct {
    name      string
    endpoint  string
    publicKey string
}{
    {"US Exit Node", "us.vpn.example.com:51820", "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg="},
    {"EU Exit Node", "eu.vpn.example.com:51820", "TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0="},
}

peers := make([]*wireguard.Peer, 0)
for _, node := range exitNodes {
    pubKey, _ := wireguard.ParsePublicKey(node.publicKey)
    peer, _ := device.AddPeer(
        pubKey,
        wireguard.NoiseSymmetricKey{},
        node.endpoint,
        []string{"0.0.0.0/0"},
    )
    peers = append(peers, peer)
}

// Use different peers for different connections
ctx := context.Background()
for _, peer := range peers {
    dialer := wireguard.NewDialer(device, peer)
    conn, _ := dialer.DialContext(ctx, "tcp", "example.com:80")
    // Use connection...
}

Configuration Files

Parse and use standard WireGuard configuration files:

import (
    "fmt"
    "log"
    "os"
    "github.com/hydrz/wireguard"
)

// Parse configuration
file, err := os.Open("wg0.conf")
if err != nil {
    log.Fatal(err)
}
config, err := wireguard.ParseConfig(file)
if err != nil {
    log.Fatal(err)
}

// Create device from config
device, err := wireguard.CreateDeviceFromConfig(config)
if err != nil {
    log.Fatal(err)
}
defer device.Close()

device.Start()

// Generate config back
generatedConfig := wireguard.GenerateConfig(device, config.Address)
fmt.Println(generatedConfig)

Configuration File Format

Standard WireGuard configuration format is supported:

[Interface]
PrivateKey = YAnz5TF+lXXJte14tji3zlMNftft3YfudVQxcKE/SXI=
ListenPort = 51820
Address = 10.0.0.1/24
MTU = 1420

[Peer]
PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

[Peer]
PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
Endpoint = 192.168.1.100:51820
AllowedIPs = 10.0.0.2/32

API Documentation

Device

The main interface for managing a WireGuard device:

• NewDevice(privateKey NoisePrivateKey) (*Device, error) - Create a new device
• Bind(addr string) error - Bind to a UDP address
• Start() error - Start the device
• Close() error - Close the device
• AddPeer(publicKey NoisePublicKey, presharedKey NoiseSymmetricKey, endpoint string, allowedIPs []string) (*Peer, error) - Add a peer
• RemovePeer(publicKey NoisePublicKey) error - Remove a peer
• PublicKey() NoisePublicKey - Get device public key

Dialer

net.Dialer-compatible interface for routing connections:

• NewDialer(device *Device, peer *Peer) *Dialer - Create a new dialer
• DialContext(ctx context.Context, network, address string) (net.Conn, error) - Dial with context
• SetTimeout(timeout time.Duration) - Set dial timeout
• SetKeepalive(keepalive time.Duration) - Set keepalive interval

Key Management

• GeneratePrivateKey() (NoisePrivateKey, error) - Generate a new private key
• ParsePrivateKey(s string) (NoisePrivateKey, error) - Parse base64-encoded private key
• EncodePrivateKey(key NoisePrivateKey) string - Encode private key to base64
• EncodePublicKey(key NoisePublicKey) string - Encode public key to base64

Testing

Run the test suite:

go test ./...

Run benchmarks:

go test -bench=. ./...

Run integration tests:

go test -tags=integration ./...

Examples

See the example directory for complete working examples:

cd example
go run main.go

Security Considerations

• Always use secure key generation: GeneratePrivateKey()
• Store private keys securely (never commit them to version control)
• Use preshared keys for additional security when possible
• Validate peer public keys before establishing connections

License

This project is open source. Please check the repository for license information.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

This implementation follows the WireGuard protocol specification and uses cryptographic primitives from golang.org/x/crypto.