WireguardBackend.hpp

1. Overview

The WireguardBackend.hpp file is a WireGuard backend public API in BastionGuard.

Defines tunnel configuration data structures and the backend contract for key generation, configuration loading, direct tunnel setup, status inspection, public-IP checks, and nftables kill-switch control.

The documentation below is generated from the supplied source and covers its API surface, runtime responsibilities, data flow, filesystem or command interactions, concurrency model, and security considerations.

2. Source Inventory

  • Original path: vpn/WireguardBackend.hpp
  • Language: C++
  • Source type: .hpp
  • Line count: 156
  • SHA-256: ac9ecd882806a4a48e8b13038ff7cf2e5e3c193b73ef9a1b0ccc503c53c4e91b

3. Dependencies

The file declares the following compile-time dependencies:

C/C++ Runtime

  • string
  • vector
  • optional
  • cstdint

4. Types and Public Contract

The file declares or implements the following principal types:

  • Struct: WgKeyPair
  • Struct: WgPeer
  • Struct: WgTunnelSpec
  • Struct: WgStatus
  • Struct: WgConfigParams
  • Struct: OpResult
  • Class: WireguardBackend

Declared Public Members

  • std::string private_key;
  • std::string public_key;
  • std::string preshared_key;
  • std::string endpoint;
  • std::string allowed_ips;
  • std::string persistent_keepalive;
  • std::string listen_port;
  • int mtu = 0;
  • bool up = false;
  • std::string interface;
  • std::string last_handshake;
  • std::uint64_t rx_bytes = 0;
  • std::uint64_t tx_bytes = 0;
  • std::string address;
  • std::string dns;
  • std::string server_public_key;
  • std::string allowed_ips = "0.0.0.0/0, ::/0";
  • std::string persistent_keepalive = "25";
  • bool ok = false;
  • int exit_code = 0;
  • std::string output;
  • explicit WireguardBackend(std::string iface = "wg0");
  • bool tooling_available(std::string* missing = nullptr) const;
  • bool load_from_conf(const std::string& conf_path, std::string* err = nullptr);
  • bool load_from_params(const WgConfigParams& p, std::string* err = nullptr);
  • bool has_spec() const { return spec_.valid();
  • } std::string configured_endpoint() const { return spec_.peers.empty() ? std::string{} : spec_.peers[0].endpoint;
  • } std::optional<WgKeyPair> generate_keys() const;
  • OpResult connect();
  • OpResult disconnect();
  • WgStatus status() const;
  • std::optional<std::string> public_ip() const;
  • OpResult killswitch_enable();
  • OpResult killswitch_disable();
  • bool killswitch_active() const;
  • const std::string& interface_name() const { return iface_;

5. API and Method Inventory

The following functions or methods are implemented in this file:

  • valid() – Implements the operation represented by this API.
  • has_spec() – Implements the operation represented by this API.
  • configured_endpoint() – Implements the operation represented by this API.
  • interface_name() – Implements the operation represented by this API.

6. Functional Architecture

Direct WireGuard Operation

  • Does not use wg-quick; it builds the tunnel with ip, wg, and an in-memory shell script.
  • Validates required tools and loads either a standard WireGuard .conf or UI-supplied parameters.
  • Generates client keys with wg genkey and wg pubkey.

Routing and DNS

  • Creates the selected WireGuard interface, assigns IPv4/IPv6 addresses, and raises the link.
  • Uses routing table 51820 and policy rules for full-tunnel AllowedIPs.
  • Adds direct routes for non-default AllowedIPs.
  • Backs up /etc/resolv.conf as /etc/resolv.conf.bastionguard.bak, writes tunnel DNS atomically, and restores the backup on disconnect.

Status and Public-IP Verification

  • Determines interface presence through unprivileged ip link show.
  • Parses endpoint and latest handshake from wg show when available.
  • Queries multiple HTTPS public-IP services through curl with a 10-second limit.

Kill-Switch

  • Creates an nftables table named bastionguard_ks.
  • Installs an output chain with a drop policy, permitting loopback, the WireGuard interface, the configured endpoint, and UDP.
  • Removes the entire nftables table when disabled.

7. Operational Flow

  1. Load or build an in-memory WireGuard tunnel specification.
  2. Validate required tools and configuration fields.
  3. Generate keys or create the interface and apply peers through wg setconf.
  4. Assign addresses, configure routes, and update DNS.
  5. Expose status and public-IP verification to the UI.
  6. Restore DNS and route state during disconnect; manage nftables kill-switch state independently.

8. Filesystem and External Command Surface

No hard-coded absolute filesystem path is declared directly in this file.

Commands or Security Primitives Referenced

  • ip
  • pkexec
  • sh
  • wg

9. Concurrency and Lifecycle

The file contains no explicit worker-thread or callback-lifetime mechanism.

10. Security Considerations

  • Tunnel creation, route changes, DNS replacement, and nftables updates require elevated privileges.
  • Private keys are held in memory and may be displayed in the configuration form.
  • Imported WireGuard configuration must be treated as sensitive input.
  • Failure paths must restore DNS, routes, and kill-switch state to avoid connectivity loss.

11. Implementation Considerations

  • This header defines the public or private class contract; behavior is implemented by the matching .cpp file unless marked inline.
  • Authorization cancellation and missing Polkit support must be surfaced as normal operation failures.

12. Licensing and Branding

The source is distributed under the GNU General Public License version 3.

The source header identifies BastionGuard™ as a trademark and states that the name and branding are not licensed under the GPL.

The software is provided without warranty, including implied warranties of merchantability or fitness for a particular purpose.

Published on:
Last updated on: