WireGuard Apple

https://github.com/wireguard/wireguard-apple
Admin
WireGuard Apple is the official WireGuard client application and network extension for iOS and...
Tokens:69,271
Snippets:455
Trust Score:9.2
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install swiftlint and go with Homebrew

Source: https://github.com/wireguard/wireguard-apple/blob/master/README.md

Install swiftlint and go 1.19 using Homebrew.

```bash
$ brew install swiftlint go
```

--------------------------------

### Basic WireGuardAdapter usage in a packet tunnel provider

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Shows the minimal setup for a packet tunnel provider using WireGuardAdapter: create the adapter with a logging closure, start the tunnel with a configuration from the protocol, and stop it. The start completion handler receives an error if the tunnel fails to start; on success the interface name is available via adapter.interfaceName.

```swift
import NetworkExtension
import WireGuardKit

class PacketTunnelProvider: NEPacketTunnelProvider {
    private lazy var adapter = WireGuardAdapter(with: self) { logLevel, message in
        os_log("%{public}s", log: .default, type: logLevel == .error ? .error : .debug, message)
    }

    override func startTunnel(options: [String: NSObject]?, completionHandler: @escaping (Error?) -> Void) {
        guard let proto = protocolConfiguration as? NETunnelProviderProtocol,
              let config = proto.asTunnelConfiguration() else {
            completionHandler(PacketTunnelProviderError.savedProtocolConfigurationIsInvalid)
            return
        }

        adapter.start(tunnelConfiguration: config) { [weak self] error in
            guard let error = error else {
                completionHandler(nil) // tunnel up; interface: self?.adapter.interfaceName
                return
            }
            // Map WireGuardAdapterError -> your provider error, notify the app,
            // then fail the tunnel:
            completionHandler(error)
        }
    }

    override func stopTunnel(with reason: NEProviderStopReason, completionHandler: @escaping () -> Void) {
        adapter.stop { _ in completionHandler() }
    }
}
```

--------------------------------

### Configure and Log Example

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/logger.md

Demonstrates one-time global logger configuration and usage of the wg_log functions for static and dynamic messages.

```swift
// One-time setup (app and extension each have their own process):
Logger.configureGlobal(tagged: "APP", withFilePath: FileManager.logFileURL?.path)

wg_log(.info, staticMessage: "Application did finish launching")
wg_log(.error, message: "Failed to load tunnel: \(error.localizedDescription)")
```

--------------------------------

### WireGuardAdapter.start(tunnelConfiguration:completionHandler:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Starts the WireGuard tunnel with the given configuration.

```APIDOC
## WireGuardAdapter.start(tunnelConfiguration:completionHandler:)

### Description
Starts the WireGuard tunnel with the given configuration.

### Method
Function

### Parameters
- **tunnelConfiguration** (TunnelConfiguration) - Required - The tunnel configuration to apply.
- **completionHandler** ( (WireGuardAdapterError?) -> Void ) - Required - A closure that receives an error if the start fails, or nil on success.

### Response
No direct return value; the result is delivered via the completion handler.
```

--------------------------------

### start(tunnelConfiguration:completionHandler:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Starts the WireGuard tunnel with the provided configuration. The completion handler is called with nil on success or a WireGuardAdapterError on failure.

```APIDOC
## start(tunnelConfiguration:completionHandler:)

### Description
Starts the WireGuard tunnel with the given configuration. The completion handler is called with nil on success or a WireGuardAdapterError on failure.

### Method
start

### Parameters
#### Parameters
- **tunnelConfiguration** (TunnelConfiguration) - Required - Full tunnel configuration.
- **completionHandler** (@escaping (WireGuardAdapterError?) -> Void) - Required - nil on success, otherwise the adapter error.

### Flow
Guard state is .stopped (else .invalidState) → start NWPathMonitor on the work queue → resolve peers (DNSResolver.resolveSync, collecting failures into .dnsResolution) → build PacketTunnelSettingsGenerator → apply generateNetworkSettings() via setTunnelNetworkSettings (throws .setNetworkSettings) → build the UAPI string → wgTurnOn on the tunnel fd (throws .cannotLocateTunnelFileDescriptor or .startWireGuardBackend(handle)) → wgDisableSomeRoamingForBrokenMobileSemantics on iOS → state becomes .started(handle, generator).
```

--------------------------------

### start(tunnelConfiguration:completionHandler:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Starts the WireGuard tunnel with the given tunnel configuration. The completion handler is called with an error if the start fails, or nil on success.

```APIDOC
## start(tunnelConfiguration:completionHandler:)

### Description
Starts the WireGuard tunnel with the provided tunnel configuration. The completion handler is called with an error if the start fails, or nil on success.

### Method
start

### Parameters
- **tunnelConfiguration** (TunnelConfiguration) - Required - The configuration to apply to the tunnel.
- **completionHandler** ((Error?) -> Void) - Required - Called with nil on success or an error on failure.

### Example
```swift
adapter.start(tunnelConfiguration: config) { error in
    if let error = error {
        // handle error
    } else {
        // tunnel started
    }
}
```
```

--------------------------------

### Full migration example

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/keychain.md

Shows how to re-key an existing config after an edit. The old item referenced by oldProtocol.passwordReference is deleted automatically after a successful add.

```swift
// Re-key an existing config after an edit (old item is deleted automatically):
let newRef = Keychain.makeReference(
    containing: editedConfig.asWgQuickConfig(),
    called: name,
    previouslyReferencedBy: oldProtocol.passwordReference
)
```

--------------------------------

### Usage examples for FileManager helpers

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/file-manager.md

Shows how the network extension configures logging, the app removes a stale error report, and the macOS app distinguishes login-item launch from user launch.

```swift
// The network extension configures logging into the app-group container:
Logger.configureGlobal(tagged: "NET", withFilePath: FileManager.logFileURL?.path)

// The app removes a stale error report after the tunnel disconnects:
if let url = FileManager.networkExtensionLastErrorFileURL {
    _ = FileManager.deleteFile(at: url)
}

// The macOS app distinguishes login-item launch from user launch:
if LaunchedAtLoginDetector.isLaunchedAtLogin(openAppleEvent: event) {
    // came back after a login-item launch
}
```

--------------------------------

### TunnelsManager.startActivation(of:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/tunnels-manager.md

Starts activation of the given tunnel, making it the active VPN tunnel.

```APIDOC
## TunnelsManager.startActivation(of:)

### Description
Starts activation of the given tunnel, making it the active VPN tunnel.

### Method
startActivation

### Parameters
- **tunnel** (TunnelContainer) - Required - The tunnel to activate.

### Request Example
```swift
tunnelsManager?.startActivation(of: home)
```

### Response
No return value.
```

--------------------------------

### DNSServer

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/dns-server-and-resolver.md

Documentation for the DNSServer struct, including its properties, initializers, and usage examples.

```APIDOC
## DNSServer

### Description
A value type representing a DNS server address, either IPv4 or IPv6.

### Properties
- `address` (IPAddress) - The server address (`IPv4Address` or `IPv6Address`). Immutable.
- `stringRepresentation` (String, computed) - The string representation of the address, e.g. `"1.1.1.1"` or `"2001:db8::1"`.

### Initializers
- `init(address: IPAddress)` - Creates a `DNSServer` with the given IP address.
- `init(from addressString: String)` - Failable initializer. Returns `nil` unless the string parses as an `IPv4Address` or `IPv6Address`.

### Example
```swift
import WireGuardKit

var interface = InterfaceConfiguration(privateKey: PrivateKey())
interface.dns = [DNSServer(from: "1.1.1.1")!, DNSServer(from: "2606:4700:4700::1111")!]
interface.dnsSearch = ["corp.example.com"]

// Failable parse:
guard let server = DNSServer(from: userInput) else {
    // not an IP address — treat as a search domain instead, like the
    // wg-quick parser does in TunnelConfiguration+WgQuickConfig.swift
}

let text = server.stringRepresentation // "1.1.1.1"
```
```

--------------------------------

### wgTurnOn

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-go-bridge.md

Starts the WireGuard backend with the given configuration and tunnel file descriptor. Returns a handle (Int32) that is used for subsequent operations.

```APIDOC
## wgTurnOn

### Description
Starts the WireGuard backend with the given configuration and tunnel file descriptor. Returns a handle (Int32) that is used for subsequent operations.

### Method
C function call

### Endpoint
wgTurnOn(config: String, tunnelFileDescriptor: Int32) -> Int32

### Parameters
- **config** (String) - Required - WireGuard configuration string in UAPI format.
- **tunnelFileDescriptor** (Int32) - Required - File descriptor for the tunnel.

### Return Value
- **Int32** - Handle to the WireGuard backend. Negative values indicate an error.

### Example
```swift
let handle = wgTurnOn(wgConfig, tunnelFileDescriptor)
if handle < 0 { throw WireGuardAdapterError.startWireGuardBackend(handle) }
```
```

--------------------------------

### Basic InterfaceConfiguration construction

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/interface-configuration.md

Basic example of constructing an InterfaceConfiguration with a fresh private key and setting all properties. The resulting interface is used to create a TunnelConfiguration named "Home" with a peers array (not shown).

```swift
import WireGuardKit

var interface = InterfaceConfiguration(privateKey: PrivateKey())
interface.addresses = [IPAddressRange(from: "10.0.0.2/32")!]
interface.listenPort = 51820
interface.mtu = 1280
interface.dns = [DNSServer(from: "1.1.1.1")!, DNSServer(from: "9.9.9.9")!]
interface.dnsSearch = ["internal.example.com"]

let config = TunnelConfiguration(name: "Home", interface: interface, peers: peers)
```

--------------------------------

### Top-level .mobileconfig payload dictionary

Source: https://github.com/wireguard/wireguard-apple/blob/master/MOBILECONFIG.md

This XML example shows the required top-level payload dictionary for a .mobileconfig file. It includes keys such as PayloadDisplayName, PayloadType, PayloadVersion, PayloadIdentifier, PayloadUUID, and PayloadContent. The PayloadContent array is empty in this example and should be filled with WireGuard configuration payload dictionaries.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadDisplayName</key>
	<string>WireGuard Demo Configuration Profile</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
	<key>PayloadIdentifier</key>
	<string>com.your-org.wireguard.FCC9BF80-C540-44C1-B243-521FDD1B2905</string>
	<key>PayloadUUID</key>
	<string>F346AAF4-53A2-4FA1-ACA3-EEE74DBED029</string>
	<key>PayloadContent</key>
	<array>
        <!-- An array of WireGuard configuration payload dictionaries -->
	</array>
</dict>
</plist>
```

--------------------------------

### getRuntimeConfiguration(completionHandler:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Retrieves the current runtime configuration as a UAPI string, or nil if the tunnel is not started.

```APIDOC
## getRuntimeConfiguration(completionHandler:)

### Description
Retrieves the current runtime configuration as a UAPI string, or nil if the tunnel is not started.

### Method
getRuntimeConfiguration

### Parameters
- **completionHandler** ((String?) -> Void) - Required - Called with the UAPI configuration string or nil.

### Example
```swift
adapter.getRuntimeConfiguration { uapiConfig in
    if let runtime = try? TunnelConfiguration(fromUapiConfig: uapiConfig ?? "", basedOn: newConfig) {
        print("peer stats:", runtime.peers)
    }
}
```
```

--------------------------------

### Catch TunnelConfiguration.ParseError cases

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/errors.md

Shows how to catch specific TunnelConfiguration.ParseError cases when parsing a wg-quick configuration. The example handles interfaceHasInvalidPrivateKey and multiplePeersWithSamePublicKey separately, then falls back to a generic catch.

```swift
do {
    let config = try TunnelConfiguration(fromWgQuickConfig: text, called: name)
} catch TunnelConfiguration.ParseError.interfaceHasInvalidPrivateKey(let value) {
    print("bad key: \(value)")
} catch TunnelConfiguration.ParseError.multiplePeersWithSamePublicKey {
    print("duplicate peers")
} catch {
    print(error)
}
```

--------------------------------

### Tunnel Provider Start Options

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/configuration.md

Options dictionary consumed by NEPacketTunnelProvider.startTunnel(options:) to correlate activation attempts with error reports.

```APIDOC
## Tunnel Provider Start Options

### Description
Options passed to `NEPacketTunnelProvider.startTunnel(options:)` to provide activation attempt correlation.

### Parameters
- **activationAttemptId** (String) - Required - App-generated UUID correlating an activation attempt with the extension's error report (`ErrorNotifier` writes it to `last-error.txt`).

### Response
No return value.
```

--------------------------------

### Building programmatically and validation

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/endpoint.md

Builds an Endpoint programmatically using NWEndpoint.Host and NWEndpoint.Port, then demonstrates guarding against malformed user input with the failable initializer. The comment lists example invalid strings that cause parsing to fail.

```swift
import Network

let host = NWEndpoint.Host("10.0.0.1")
let port = NWEndpoint.Port(rawValue: 51820)!
let endpoint = Endpoint(host: host, port: port)

// Failable parsing — guard against malformed user input:
guard let parsed = Endpoint(from: userSuppliedString) else {
    // e.g. "missing port", "[::1]80", "/with space/" — all fail
    return
}
```

--------------------------------

### PrivateKey

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/keys.md

Documentation for the PrivateKey type, including initialization, public key derivation, and usage examples for encoding, parsing, and pre-shared keys.

```APIDOC
## PrivateKey

### Description
Represents a WireGuard private key. Can be initialized to generate a fresh random key, and provides a derived public key.

### Initializer
- `convenience public init()` - Generates a fresh random private key via `curve25519_generate_private_key` (`x25519.c`). Non-failable.

### Properties
- `public var publicKey: PublicKey` - Derives the public key via `curve25519_derive_public_key`.

### Example: Generate keys and encode them
```swift
import WireGuardKit

let privateKey = PrivateKey()
print(privateKey.base64Key)   // e.g. "mInDaw06K0NgfULRObHJjkWD3ahUC8XC1tVjIf6W+Vo="
print(privateKey.hexKey)      // 64 lowercase hex chars
print(privateKey.publicKey.base64Key)

var interface = InterfaceConfiguration(privateKey: privateKey)
// wg-quick serialization uses the base64 form:
print(interface.privateKey.base64Key)
// UAPI uses the hex form:
print(interface.privateKey.hexKey)
```

### Example: Parse keys from user input with error handling
```swift
// Accept either encoding when importing a config:
func makePublicKey(from stored: String) -> PublicKey? {
    if let key = PublicKey(base64Key: stored) { return key }
    return PublicKey(hexKey: stored)
}

guard let peerPublicKey = makePublicKey(from: "JRI8Xc0zKP9kXk8qP84NdUQA04h6DLfFbwJn4g+/PFs=") else {
    // invalid — wg-quick parser would throw
    // ParseError.peerHasInvalidPublicKey here
    return
}

// Raw round-trip:
let raw = Data(base64Encoded: privateKey.base64Key)!
let restored = PrivateKey(rawValue: raw)
print(restored == privateKey) // true (constant-time key_eq comparison)
```

### Example: Pre-shared key
```swift
var peer = PeerConfiguration(publicKey: peerPublicKey)
if let psk = PreSharedKey(base64Key: "iFjqAtbjebdZBGBMIPAwx6KYM1E3w1XNoiB9/6SgYGs=") {
    peer.preSharedKey = psk
}
```
```

--------------------------------

### Handle runtime configuration request

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/endpoints.md

Handles the app message in the network extension. Responds with the UTF-8 UAPI configuration string or nil if the tunnel is not started or the query fails. Any payload other than exactly [0x00] is answered with nil.

```swift
override func handleAppMessage(_ messageData: Data, completionHandler: ((Data?) -> Void)? = nil) {
    guard let completionHandler = completionHandler else { return }

    if messageData.count == 1 && messageData[0] == 0 {
        adapter.getRuntimeConfiguration { settings in
            var data: Data?
            if let settings = settings {
                data = settings.data(using: .utf8)!
            }
            completionHandler(data)
        }
    } else {
        completionHandler(nil)
    }
}
```

--------------------------------

### PacketTunnelProvider class with WireGuardAdapter

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/packet-tunnel-provider.md

Defines the PacketTunnelProvider class, which lazily creates a WireGuardAdapter and wires it to the wg_log function for logging. The adapter is used to start and stop the tunnel and to get runtime configuration.

```swift
class PacketTunnelProvider: NEPacketTunnelProvider {
    private lazy var adapter: WireGuardAdapter = {
        return WireGuardAdapter(with: self) { logLevel, message in
            wg_log(logLevel.osLogLevel, message: message)
        }
    }()
    ...
}
```

--------------------------------

### init(tunnelConfiguration:previouslyFrom:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/netunnel-provider-protocol.md

Initializes a NETunnelProviderProtocol from a TunnelConfiguration, storing the wg-quick config in the keychain and setting provider properties.

```APIDOC
## init(tunnelConfiguration:previouslyFrom:)

### Description
Initializes a NETunnelProviderProtocol from a TunnelConfiguration, storing the wg-quick config in the keychain and setting provider properties.

### Method
Initializer

### Signature
`convenience init?(tunnelConfiguration: TunnelConfiguration, previouslyFrom old: NEVPNProtocol? = nil)`

### Parameters
- `tunnelConfiguration` (TunnelConfiguration) - Required - Source configuration.
- `old` (NEVPNProtocol?) - Optional - Previous protocol whose passwordReference is replaced (old reference deleted after success).

### Behavior
- Requires `tunnelConfiguration.name != nil` and a valid `Bundle.main.bundleIdentifier`; else returns `nil`.
- Sets `providerBundleIdentifier = "\(appId).network-extension"`.
- Stores the wg-quick text (`tunnelConfiguration.asWgQuickConfig()`) in the keychain via `Keychain.makeReference(containing:called:previouslyReferencedBy:)`; `nil` result → initializer returns `nil`.
- macOS: sets `providerConfiguration = ["UID": getuid()]` (per-user tunnels).
- Derives `serverAddress` from peer endpoints: exactly 1 endpoint → its `stringRepresentation`; 0 → `"Unspecified"`; >1 → `"Multiple endpoints"`.

### Returns
`NETunnelProviderProtocol?` - The initialized protocol, or `nil` on failure.
```

--------------------------------

### init(fromWgQuickConfig:called:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/tunnel-configuration.md

Initializes a TunnelConfiguration by parsing a wg-quick configuration string.

```APIDOC
## init(fromWgQuickConfig:called:)

### Description
Initializes a TunnelConfiguration by parsing a WireGuard configuration string in wg-quick(8)/wg(8) format. The optional `name` parameter assigns a tunnel name to the configuration.

### Method
init

### Signature
`convenience init(fromWgQuickConfig wgQuickConfig: String, called name: String? = nil) throws`

### Parameters
- **wgQuickConfig** (String) - Required - WireGuard config text in wg-quick(8)/wg(8) format.
- **name** (String?) - Optional - Tunnel name assigned to `self.name`. Defaults to `nil`.

### Parsing Rules
- Lines are split on whitespace; `#` starts a comment.
- Attributes are `key = value` lines (case-insensitive keys).
- Sections are `[Interface]` and `[Peer]` (case-insensitive).
- Supported interface keys: `PrivateKey`, `ListenPort`, `Address`, `DNS`, `MTU`.
- Supported peer keys: `PublicKey`, `PresharedKey`, `AllowedIPs`, `Endpoint`, `PersistentKeepalive`.
- Multi-value keys are `Address`, `AllowedIPs`, `DNS`, comma-joined.
- DNS entries that fail `DNSServer(from:)` are treated as DNS search domains.
- `FwMark`, `Table`, `PreUp`, `PostUp`, `PreDown`, `PostDown`, `SaveConfig` are not supported.

### Throws
- `TunnelConfiguration.ParseError` on any malformed input.

### Source Location
`Sources/Shared/Model/TunnelConfiguration+WgQuickConfig.swift:38`
```

--------------------------------

### init(publicKey:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/peer-configuration.md

Initializes a PeerConfiguration with a required public key. All other properties default to empty or nil and can be mutated afterwards.

```APIDOC
## init(publicKey:)

### Description
Initializes a PeerConfiguration with a required public key. All other properties default to empty or nil and can be mutated afterwards.

### Parameters
- **publicKey** (PublicKey) - Required - The peer's public key.

### Notes
All other properties default to empty/nil and may be mutated afterwards.
```

--------------------------------

### init(with:logHandler:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Initializer for the WireGuard adapter, accepting a packet tunnel provider and a log handler.

```APIDOC
## init(with:logHandler:)

### Description
Initializes a WireGuard adapter with a packet tunnel provider and a log handler. The initializer installs the global backend logger (`wgSetLogger`) with an unretained self context; `deinit` unregisters it, cancels the `NWPathMonitor`, and calls `wgTurnOff` if started.

### Parameters
- **packetTunnelProvider** (NEPacketTunnelProvider) - Required - Stored weakly. Used to call `setTunnelNetworkSettings` and set `reasserting`.
- **logHandler** (@escaping LogHandler) - Required - Closure `(WireGuardLogLevel, String) -> Void` invoked for every backend log line.

```

--------------------------------

### PeerConfiguration

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/peer-configuration.md

Configuration object for a WireGuard peer, including setup and runtime statistics.

```APIDOC
## PeerConfiguration

### Description
Represents the configuration for a single WireGuard peer, including its public key, endpoint, allowed IPs, and optional pre-shared key and persistent keep-alive interval.

### Properties
- **publicKey** (PublicKey) - Required - The peer's public key.
- **endpoint** (Endpoint) - Optional - The endpoint (host and port) of the peer.
- **allowedIPs** ([IPAddressRange]) - Optional - List of IP address ranges allowed for this peer.
- **persistentKeepAlive** (Int) - Optional - Interval in seconds for sending persistent keep-alive packets.
- **preSharedKey** (PreSharedKey) - Optional - Pre-shared key for additional security.
- **rxBytes** (UInt64?) - Optional - Runtime statistic: number of bytes received (populated by UAPI parser).
- **txBytes** (UInt64?) - Optional - Runtime statistic: number of bytes transmitted (populated by UAPI parser).
- **lastHandshakeTime** (Date?) - Optional - Runtime statistic: time of last handshake (populated by UAPI parser).

### Usage Example
```swift
import WireGuardKit

var peer = PeerConfiguration(publicKey: PublicKey(base64Key: "JRI8Xc0zKP9kXk8qP84NdUQA04h6DLfFbwJn4g+/PFs=")!)
peer.endpoint = Endpoint(from: "demo.wireguard.com:12912")
peer.allowedIPs = [IPAddressRange(from: "0.0.0.0/0")!, IPAddressRange(from: "::/0")!]
peer.persistentKeepAlive = 25
```

### Notes
- `rxBytes`, `txBytes`, and `lastHandshakeTime` are only populated by the UAPI parser (see `TunnelConfiguration+UapiConfig.swift`); they are never written by `asWgQuickConfig()`.
```

--------------------------------

### init(fromUapiConfig:basedOn:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/tunnel-configuration.md

Swift initializer that parses UAPI/IPC configuration text into a TunnelConfiguration object.

```APIDOC
## init(fromUapiConfig:basedOn:)

### Description
Parses the UAPI/IPC format produced by `wgGetConfig` (the wireguard-go backend) into a `TunnelConfiguration`. Supported interface keys: `private_key`, `listen_port`, `fwmark`. Supported peer keys: `public_key`, `preshared_key`, `allowed_ip` (repeatable), `endpoint`, `persistent_keepalive_interval`, `last_handshake_time_sec`, `last_handshake_time_nsec`, `rx_bytes`, `tx_bytes`, `protocol_version`. Keys are parsed as hex (`PrivateKey(hexKey:)`, etc.). Values of `0` are treated as "unset": a zero `listen_port` leaves `interface.listenPort` nil, a zero `preshared_key` is dropped, zero `rx_bytes`/`tx_bytes`/`persistent_keepalive_interval` are dropped.

### Method
Initializer (Swift)

### Signature
`convenience init(fromUapiConfig uapiConfig: String, basedOn base: TunnelConfiguration? = nil) throws`

### Parameters
- `uapiConfig` (String) - Required - UAPI config text (newline-separated `key=value` lines; a blank line or a new `public_key` starts the next section).
- `base` (TunnelConfiguration?) - Optional - Base config whose `addresses`, `dns`, `dnsSearch`, `mtu` and `name` are carried over (UAPI output carries no addresses/DNS/MTU). Default: `nil`.

### Throws
`TunnelConfiguration.ParseError` (same enum as the wg-quick parser), plus `interfaceHasNoPrivateKey`, `interfaceHasInvalidPrivateKey`, `peerHasNoPublicKey`, `peerHasInvalidPublicKey`, `peerHasInvalidPreSharedKey`, `peerHasInvalidAllowedIP`, `peerHasInvalidEndpoint`, `peerHasInvalidPersistentKeepAlive`, `peerHasInvalidTransferBytes`, `peerHasInvalidLastHandshakeTime`, `peerHasUnrecognizedKey`, `interfaceHasUnrecognizedKey`, `multipleEntriesForKey`, `multiplePeersWithSamePublicKey`, `noInterface`, `invalidLine`, `multipleInterfaces`.
```

--------------------------------

### Endpoint

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/endpoint.md

Documentation for the Endpoint struct in WireGuardKit, including initializers, properties, methods, and usage examples.

```APIDOC
## Endpoint

### Description
Immutable struct representing a peer endpoint: a host (IP address or hostname) plus a UDP port. Wraps Apple's `Network` framework types.

### Initializer

#### `init(host:port:)`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `host` | `NWEndpoint.Host` | yes | — | `.name(name, interface)`, `.ipv4(IPv4Address)`, or `.ipv6(IPv6Address)`. |
| `port` | `NWEndpoint.Port` | yes | — | UDP port. |

#### `init?(from string: String)`

Parses an endpoint string. The format mirrors the `parse_endpoint` function in wireguard-tools `src/config.c`:

- `host:port` — IPv4-style, e.g. `demo.wireguard.com:12912`, `127.0.0.1:80`
- `[host]:port` — IPv6-style, e.g. `[::1]:80` (the `]` must be followed by `:`)
- The port must parse via `NWEndpoint.Port(String)`; host characters must all be within `CharacterSet.urlHostAllowed`.

Returns `nil` for: empty strings, missing `:`, IPv6-style strings without a closing `]` or without a port, unparseable ports, or hosts containing characters outside `urlHostAllowed`.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `host` | `NWEndpoint.Host` | Endpoint host. Immutable. |
| `port` | `NWEndpoint.Port` | Endpoint port. Immutable. |
| `stringRepresentation` | `String` (computed, get-only) | See below. |

#### `stringRepresentation`

Formats the endpoint: `hostname:port` for `.name`, `address:port` for IPv4, `[address]:port` for IPv6. Traps with `fatalError()` on unknown `NWEndpoint.Host` cases (`@unknown default`).

### Methods

#### `hasHostAsIPAddress() -> Bool`

Returns `true` when `host` is `.ipv4` or `.ipv6` (already numeric, no DNS resolution needed), `false` for `.name`.

#### `hostname() -> String?`

Returns the hostname when `host` is `.name(name, _)`; returns `nil` for IP hosts.

### Examples

#### Basic: parsing and formatting

```swift
import WireGuardKit

let endpoint = Endpoint(from: "demo.wireguard.com:12912")!
print(endpoint.stringRepresentation) // "demo.wireguard.com:12912"
print(endpoint.hasHostAsIPAddress()) // false
print(endpoint.hostname() as Any)    // Optional("demo.wireguard.com")

let ipv6 = Endpoint(from: "[2001:db8::1]:12345")!
print(ipv6.stringRepresentation)     // "[2001:db8::1]:12345"
print(ipv6.hasHostAsIPAddress())     // true
print(ipv6.hostname() as Any)        // nil
```

#### Building programmatically and validation

```swift
import Network

let host = NWEndpoint.Host("10.0.0.1")
let port = NWEndpoint.Port(rawValue: 51820)!
let endpoint = Endpoint(host: host, port: port)

// Failable parsing — guard against malformed user input:
guard let parsed = Endpoint(from: userSuppliedString) else {
    // e.g. "missing port", "[::1]80", "/with space/" — all fail
    return
}
```

#### Error handling with failable parsing

```swift
func endpointOrThrow(_ input: String) -> Endpoint {
    guard let endpoint = Endpoint(from: input) else {
        fatalError("Invalid endpoint string: \(input)")
    }
    return endpoint
}
```
```

--------------------------------

### TunnelsManagerActivationAttemptError enum

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/types.md

Defines errors for activation attempts, including failures during start, save, load, and excessive errors.

```swift
enum TunnelsManagerActivationAttemptError: WireGuardAppError {
    case tunnelIsNotInactive
    case failedWhileStarting(systemError: Error)
    case failedWhileSaving(systemError: Error)
    case failedWhileLoading(systemError: Error)
    case failedBecauseOfTooManyErrors(lastSystemError: Error)
}
```

--------------------------------

### Throwing Initializer Usage

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/logger.md

Demonstrates manual instantiation of the Logger class and handling the openFailure error.

```swift
do {
    let logger = try Logger(tagged: "CUSTOM", withFilePath: path)
    logger.log(message: "hello")
    // ...
} catch Logger.LoggerError.openFailure {
    print("cannot open ring log at \(path)")
}
```

--------------------------------

### Build a tunnel configuration programmatically

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/tunnel-configuration.md

Constructs an InterfaceConfiguration and PeerConfiguration, then creates a TunnelConfiguration named "Demo". Requires a private key and a peer public key; the endpoint and allowed IPs are set directly.

```swift
import WireGuardKit

private var interface = InterfaceConfiguration(privateKey: PrivateKey())
interface.addresses = [IPAddressRange(from: "10.10.1.2/24")!]
interface.dns = [DNSServer(from: "1.1.1.1")!]
interface.mtu = 1420

var peer = PeerConfiguration(publicKey: PublicKey(base64Key: "JRI8Xc0zKP9kXk8qP84NdUQA04h6DLfFbwJn4g+/PFs=")!)
peer.endpoint = Endpoint(from: "demo.wireguard.com:12912")
peer.allowedIPs = [IPAddressRange(from: "0.0.0.0/0")!]

let config = TunnelConfiguration(name: "Demo", interface: interface, peers: [peer])
```

--------------------------------

### WireGuardAdapter.init(with:logHandler:)

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Initializes a new WireGuardAdapter instance with the given packet tunnel provider and a log handler.

```APIDOC
## WireGuardAdapter.init(with:logHandler:)

### Description
Initializes a new WireGuardAdapter instance with the given packet tunnel provider and a log handler.

### Method
Initializer

### Parameters
- **packetTunnelProvider** (NEPacketTunnelProvider) - Required - The packet tunnel provider.
- **logHandler** (LogHandler) - Required - A closure that receives log messages.

### Response
No return value.
```

--------------------------------

### DNSServer usage with failable initializer

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/dns-server-and-resolver.md

Shows how to create DNSServer instances from IP address strings using the failable initializer. The initializer returns nil for non-IP strings, so guard-let is used to fall back to treating the input as a search domain. The stringRepresentation property yields the address as a string.

```swift
import WireGuardKit

var interface = InterfaceConfiguration(privateKey: PrivateKey())
interface.dns = [DNSServer(from: "1.1.1.1")!, DNSServer(from: "2606:4700:4700::1111")!]
interface.dnsSearch = ["corp.example.com"]

// Failable parse:
guard let server = DNSServer(from: userInput) else {
    // not an IP address — treat as a search domain instead, like the
    // wg-quick parser does in TunnelConfiguration+WgQuickConfig.swift
}

let text = server.stringRepresentation // "1.1.1.1"
```

--------------------------------

### Saving a tunnel to system preferences

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/netunnel-provider-protocol.md

Creates a tunnel configuration from a wg-quick text, sets it on a NETunnelProviderManager, enables it, and saves to preferences. On error, destroys the keychain reference.

```swift
let config = try TunnelConfiguration(fromWgQuickConfig: text, called: "Office")

let networkExtensionManager = NETunnelProviderManager()
networkExtensionManager.setTunnelConfiguration(config)   // protocol + keychain reference
networkExtensionManager.isEnabled = true

networkExtensionManager.saveToPreferences { error in
    if let error {
        (networkExtensionManager.protocolConfiguration as? NETunnelProviderProtocol)?
            .destroyConfigurationReference() // roll back the keychain item
        return
    }
    // saved — the extension can now load it via asTunnelConfiguration()
}
```

--------------------------------

### TunnelConfiguration.ParseError

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/errors.md

Documentation for the TunnelConfiguration.ParseError error type, which is thrown during configuration parsing. It includes all error cases, their associated values, and a Swift example of how to catch specific errors.

```APIDOC
## TunnelConfiguration.ParseError

### Description
An error type thrown when parsing a WireGuard configuration fails. It provides detailed reasons for each parsing failure.

### Cases
- **invalidLine** (String.SubSequence) - Triggered when a line is encountered that does not contain `=` and is not a section header.
- **noInterface** - No `[Interface]` section found or no interface attributes collected.
- **multipleInterfaces** - More than one `[Interface]` section detected.
- **interfaceHasNoPrivateKey** - Interface parsed without a private key.
- **interfaceHasInvalidPrivateKey** (String) - Private key is unparseable (base64 in wg-quick, hex in UAPI).
- **interfaceHasInvalidListenPort** (String) - `ListenPort`/`listen_port` is not a valid `UInt16`.
- **interfaceHasInvalidAddress** (String) - `Address` entry fails to parse into an `IPAddressRange`.
- **interfaceHasInvalidDNS** (String) - Declared but not raised by the wg-quick collate path; DNS failures become search domains.
- **interfaceHasInvalidMTU** (String) - `MTU` is not a valid `UInt16`.
- **interfaceHasUnrecognizedKey** (String) - Unknown key inside `[Interface]`.
- **peerHasNoPublicKey** - Peer section lacks a public key.
- **peerHasInvalidPublicKey** (String) - Public key is unparseable.
- **peerHasInvalidPreSharedKey** (String) - Pre-shared key is unparseable.
- **peerHasInvalidAllowedIP** (String) - `AllowedIPs`/`allowed_ip` entry fails parsing.
- **peerHasInvalidEndpoint** (String) - `Endpoint` fails to parse.
- **peerHasInvalidPersistentKeepAlive** (String) - Not a valid `UInt16`.
- **peerHasInvalidTransferBytes** (String) - `rx_bytes`/`tx_bytes` not a valid `UInt64`. (Only UAPI)
- **peerHasInvalidLastHandshakeTime** (String) - `last_handshake_time_sec`/`_nsec` not valid `UInt64`. (Only UAPI)
- **peerHasUnrecognizedKey** (String) - Unknown key inside `[Peer]`.
- **multiplePeersWithSamePublicKey** - Duplicate peer public keys in one config.
- **multipleEntriesForKey** (String) - A non-repeatable key appears twice (address, allowedips/allowed_ip, dns are repeatable).

### Example Usage
```swift
do {
    let config = try TunnelConfiguration(fromWgQuickConfig: text, called: name)
} catch TunnelConfiguration.ParseError.interfaceHasInvalidPrivateKey(let value) {
    print("bad key: \(value)")
} catch TunnelConfiguration.ParseError.multiplePeersWithSamePublicKey {
    print("duplicate peers")
} catch {
    print(error)
}
```
```

--------------------------------

### Open WireGuard.xcodeproj in Xcode

Source: https://github.com/wireguard/wireguard-apple/blob/master/README.md

Open the WireGuard Xcode project.

```bash
$ open WireGuard.xcodeproj
```

--------------------------------

### Round-trip on-demand options

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/tunnel-container.md

Apply SSID-specific on-demand rules to a tunnel provider and later reconstruct the option from the manager. The example shows creating an ActivateOnDemandOption for specific SSIDs, applying it, and restoring it to verify equality.

```swift
// Applies SSID-specific rules to a tunnel provider:
let option = ActivateOnDemandOption.anyInterface(.onlySpecificSSIDs(["CoffeeShop", "Office"]))
option.apply(on: tunnelProviderManager)

// Later, reconstruct from the manager:
let restored = ActivateOnDemandOption(from: tunnelProviderManager)
assert(restored == option)
```

--------------------------------

### asWgQuickConfig()

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/tunnel-configuration.md

Serializes the TunnelConfiguration to a wg-quick configuration string.

```APIDOC
## asWgQuickConfig()

### Description
Serializes the configuration back to wg-quick format. The output contains an `[Interface]` section with `PrivateKey`, optional `ListenPort`, `Address`, `DNS`, and `MTU`, followed by one `[Peer]` block per peer with `PublicKey`, optional `PresharedKey`, `AllowedIPs`, `Endpoint`, and `PersistentKeepalive`.

### Method
func

### Signature
`func asWgQuickConfig() -> String`

### Returns
- **String** - The configuration serialized in wg-quick format.

### Notes
- `rxBytes`, `txBytes`, and `lastHandshakeTime` are not serialized.

### Source Location
`Sources/Shared/Model/TunnelConfiguration+WgQuickConfig.swift:126`
```

--------------------------------

### PeerConfiguration

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/peer-configuration.md

Documentation for the PeerConfiguration struct, including its properties and initializer.

```APIDOC
## PeerConfiguration

### Description
Mutable struct describing a single WireGuard peer (the `[Peer]` portion of a wg-quick configuration): public key, optional pre-shared key, allowed IPs, endpoint, keep-alive, and read-only runtime statistics.

### Declaration
```swift
public struct PeerConfiguration {
    public var publicKey: PublicKey
    public var preSharedKey: PreSharedKey?
    public var allowedIPs = [IPAddressRange]()
    public var endpoint: Endpoint?
    public var persistentKeepAlive: UInt16?
    public var rxBytes: UInt64?
    public var txBytes: UInt64?
    public var lastHandshakeTime: Date?

    public init(publicKey: PublicKey)
}
```

### Properties
- **publicKey** (`PublicKey`) - Required - The peer's public key.
- **preSharedKey** (`PreSharedKey?`) - Optional - Optional pre-shared key for additional post-quantum resistance.
- **allowedIPs** (`[IPAddressRange]`) - Optional - Allowed IP ranges for this peer (routing).
- **endpoint** (`Endpoint?`) - Optional - Peer endpoint (host + port). `nil` = no fixed endpoint (roaming / incoming-only).
- **persistentKeepAlive** (`UInt16?`) - Optional - Keep-alive interval in seconds; commonly 25 for NAT traversal.
- **rxBytes** (`UInt64?`) - Optional - Runtime received byte counter (populated from UAPI output, not serialized to wg-quick).
- **txBytes** (`UInt64?`) - Optional - Runtime transmitted byte counter (populated from UAPI output).
- **lastHandshakeTime** (`Date?`) - Optional - Time of the last successful handshake (populated from UAPI output).

### Initializer
- `init(publicKey: PublicKey)` - Creates a peer configuration with the given public key.
```

--------------------------------

### Create and edit Developer.xcconfig

Source: https://github.com/wireguard/wireguard-apple/blob/master/README.md

Create the Developer.xcconfig file from the template and edit it to populate the developer team ID.

```bash
$ cp Sources/WireGuardApp/Config/Developer.xcconfig.template Sources/WireGuardApp/Config/Developer.xcconfig
$ vim Sources/WireGuardApp/Config/Developer.xcconfig
```

--------------------------------

### InterfaceConfiguration Initializer

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/configuration.md

Initializes an InterfaceConfiguration with a required private key and optional properties for addresses, listen port, MTU, DNS, and DNS search domains.

```APIDOC
## InterfaceConfiguration Initializer

### Description
Creates an interface configuration for a WireGuard tunnel.

### Method
Initializer

### Signature
`public init(privateKey: PrivateKey)`

### Parameters
- **privateKey** (PrivateKey) - Required - Interface private key.
- **addresses** ([IPAddressRange]) - Optional - Tunnel addresses (routes, gateway = address itself). Default: `[]`.
- **listenPort** (UInt16?) - Optional - UDP listen port; `nil` = random. Default: `nil`.
- **mtu** (UInt16?) - Optional - MTU; `nil`/`0` = automatic (iOS 1280, macOS 80-byte overhead). Default: `nil`.
- **dns** ([DNSServer]) - Optional - DNS servers; non-empty ⇒ `matchDomains = [""]`. Default: `[]`.
- **dnsSearch** ([String]) - Optional - DNS search domains. Default: `[]`.

### Response
No return value.
```

--------------------------------

### WireGuardAdapter class declaration

Source: https://github.com/wireguard/wireguard-apple/blob/master/_autodocs/api-reference/wireguard-adapter.md

Public interface of the WireGuardAdapter class. Use it inside a packet tunnel provider to manage the WireGuard tunnel lifecycle: start, stop, update, and retrieve runtime configuration. All operations are serialized on a private DispatchQueue named "WireGuardAdapterWorkQueue".

```swift
public class WireGuardAdapter {
    public typealias LogHandler = (WireGuardLogLevel, String) -> Void
    ...
    public var interfaceName: String? { ... }

    public init(with packetTunnelProvider: NEPacketTunnelProvider, logHandler: @escaping LogHandler)

    public func getRuntimeConfiguration(completionHandler: @escaping (String?) -> Void)
    public func start(tunnelConfiguration: TunnelConfiguration, completionHandler: @escaping (WireGuardAdapterError?) -> Void)
    public func stop(completionHandler: @escaping (WireGuardAdapterError?) -> Void)
    public func update(tunnelConfiguration: TunnelConfiguration, completionHandler: @escaping (WireGuardAdapterError?) -> Void)
}
```
Tokens:
Raw