TunBuilder methods, loosely based on the Android VpnService.Builder abstraction. More...

#include <base.hpp>

Inheritance diagram for openvpn::TunBuilderBase:

Public Member Functions
virtual bool	tun_builder_new ()
	Callback to construct a new TunBuilder. This function should be called first.

virtual bool	tun_builder_set_layer (int layer)
	Optional callback that indicates OSI layer to be used.

virtual bool	tun_builder_set_remote_address (const std::string &address, bool ipv6)
	Callback to set the address of the remote server.

virtual bool	tun_builder_add_address (const std::string &address, int prefix_length, const std::string &gateway, bool ipv6, bool net30)
	Callback to add a network address to the VPN interface.

virtual bool	tun_builder_set_route_metric_default (int metric)
	Optional callback to set default value for route metric.

virtual bool	tun_builder_reroute_gw (bool ipv4, bool ipv6, unsigned int flags)
	Callback to reroute the default gateway to the VPN interface.

virtual bool	tun_builder_add_route (const std::string &address, int prefix_length, int metric, bool ipv6)
	Callback to add a route to the VPN interface.

virtual bool	tun_builder_exclude_route (const std::string &address, int prefix_length, int metric, bool ipv6)
	Callback to exclude route from VPN interface.

virtual bool	tun_builder_set_dns_options (const DnsOptions &dns)
	Callback to set DNS related options to VPN interface.

virtual bool	tun_builder_set_mtu (int mtu)
	Callback to set the MTU of the VPN interface.

virtual bool	tun_builder_set_session_name (const std::string &name)
	Sets the session name for the TunBuilder.

virtual bool	tun_builder_add_proxy_bypass (const std::string &bypass_host)
	Callback to add a host which should bypass the proxy.

virtual bool	tun_builder_set_proxy_auto_config_url (const std::string &url)
	Callback to set the proxy "Auto Config URL".

virtual bool	tun_builder_set_proxy_http (const std::string &host, int port)
	Callback to set the HTTP proxy.

virtual bool	tun_builder_set_proxy_https (const std::string &host, int port)
	Set the HTTPS proxy for the TunBuilder session.

virtual bool	tun_builder_add_wins_server (const std::string &address)
	Callback to add a Windows WINS server to the VPN interface.

virtual bool	tun_builder_set_allow_family (int af, bool allow)
	Indicates whether traffic of a certain address family (AF_INET or AF_INET6) should be blocked or allowed.

virtual bool	tun_builder_set_allow_local_dns (bool allow)
	Optional callback that indicates whether local DNS traffic should be blocked or allowed to prevent DNS queries from leaking while the tunnel is connected.

virtual int	tun_builder_establish ()
	Callback to establish the VPN tunnel.

virtual bool	tun_builder_persist ()
	Determines if the TUN interface can be persisted.

virtual std::vector< std::string >	tun_builder_get_local_networks (bool ipv6)
	Retrieves a list of local networks to exclude from the VPN network.

virtual void	tun_builder_establish_lite ()
	Indicates a reconnection with persisted TUN state.

virtual void	tun_builder_teardown (bool disconnect)
	Indicates that tunnel is being torn down.

virtual	~TunBuilderBase ()=default
	Virtual destructor for the TunBuilderBase class.

Detailed Description

TunBuilder methods, loosely based on the Android VpnService.Builder abstraction.

These methods comprise an abstraction layer that allows the OpenVPN C++ core to call out to external methods for establishing the tunnel, adding routes, etc.

All methods returning bool use the return value to indicate success (true) or failure (false).

tun_builder_new() should be called first, then arbitrary setter methods, and finally tun_builder_establish() to return the socket descriptor for the session.

IP addresses are pre-validated before being passed to these methods.

This interface is based on Android's VpnService.Builder.

Definition at line 41 of file base.hpp.

Constructor & Destructor Documentation

◆ ~TunBuilderBase()

virtual openvpn::TunBuilderBase::~TunBuilderBase ( )

virtualdefault

Virtual destructor for the TunBuilderBase class.

Ensures derived classes can clean up resources properly.

Member Function Documentation

◆ tun_builder_add_address()

virtual bool openvpn::TunBuilderBase::tun_builder_add_address	(	const std::string &	address,
		int	prefix_length,
		const std::string &	gateway,
		bool	ipv6,
		bool	net30
	)

inlinevirtual

Callback to add a network address to the VPN interface.

This method may be called multiple times within a single TunBuilder session.

Parameters

address	The network address to add.
prefix_length	The prefix length of the network address.
gateway	An optional gateway address.
ipv6	A boolean indicating whether the address is IPv6.
net30	A boolean indicating whether to use a net30 topology.

Returns: true if the address was successfully added, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 101 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_add_proxy_bypass()

virtual bool openvpn::TunBuilderBase::tun_builder_add_proxy_bypass ( const std::string & bypass_host )

inlinevirtual

Callback to add a host which should bypass the proxy.

This method can be called multiple times within the same TunBuilder session.

Parameters

bypass_host A string representing the host that should bypass the proxy.

Returns: Returns true if the bypass host was successfully added, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 240 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_add_route()

virtual bool openvpn::TunBuilderBase::tun_builder_add_route	(	const std::string &	address,
		int	prefix_length,
		int	metric,
		bool	ipv6
	)

inlinevirtual

Callback to add a route to the VPN interface.

This method may be called multiple times per TunBuilder session.

Parameters

address	The address to add the route for.
prefix_length	The prefix length associated with the route.
metric	The metric for the route. It is optional and should be ignored if it is less than 0.
ipv6	Boolean indicating whether the address is IPv6.

Returns: true if the route was successfully added, false otherwise

Reimplemented in openvpn::TunBuilderCapture, and unittests::TunBuilderMock.

Definition at line 158 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_add_wins_server()

virtual bool openvpn::TunBuilderBase::tun_builder_add_wins_server ( const std::string & address )

inlinevirtual

Callback to add a Windows WINS server to the VPN interface.

This function is called to add a WINS server address to the VPN interface. WINS server addresses are always IPv4.

Note: This function may be called more than once per TunBuilder session. It is guaranteed to be called after tun_builder_reroute_gw().

Parameters

address The IPv4 address of the WINS server to be added.

Returns: true if the WINS server was successfully added, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 305 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_establish()

virtual int openvpn::TunBuilderBase::tun_builder_establish ( )

inlinevirtual

Callback to establish the VPN tunnel.

This method returns a file descriptor to the tunnel, which the caller will henceforth own. It returns -1 if the tunnel could not be established. This function is always called last after the TunBuilder session has been configured.

Returns: File descriptor to the tunnel, or -1 if the tunnel could not be established

Definition at line 361 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_establish_lite()

virtual void openvpn::TunBuilderBase::tun_builder_establish_lite ( )

inlinevirtual

Indicates a reconnection with persisted TUN state.

This function is responsible for handling reconnections while maintaining the persistent TUN state.

Definition at line 406 of file base.hpp.

◆ tun_builder_exclude_route()

virtual bool openvpn::TunBuilderBase::tun_builder_exclude_route	(	const std::string &	address,
		int	prefix_length,
		int	metric,
		bool	ipv6
	)

inlinevirtual

Callback to exclude route from VPN interface.

This method may be called more than once per TunBuilder session.

Parameters

address	The IP address for the route to be excluded.
prefix_length	The prefix length for the IP address.
metric	The route metric. This parameter should be ignored if it is less than 0.
ipv6	A boolean flag indicating whether the IP address is IPv6 or not.

Returns: true if the route was successfully excluded, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 178 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_get_local_networks()

virtual std::vector< std::string > openvpn::TunBuilderBase::tun_builder_get_local_networks ( bool ipv6 )

inlinevirtual

Retrieves a list of local networks to exclude from the VPN network.

When the exclude local network option is enabled, this function is called to get a list of local networks. Routes are then generated to exclude these networks from the VPN network.

Parameters

ipv6	Indicates whether to retrieve IPv6 networks (`true`) or IPv4 networks (`false`).

Returns: A vector containing CIDR representations of the local networks (e.g., "192.168.0.0/24")

Definition at line 395 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_new()

virtual bool openvpn::TunBuilderBase::tun_builder_new ( )

inlinevirtual

Callback to construct a new TunBuilder. This function should be called first.

Returns: true if the TunBuilder was successfully created, false otherwise

Reimplemented in Client.

Definition at line 50 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_persist()

virtual bool openvpn::TunBuilderBase::tun_builder_persist ( )

inlinevirtual

Determines if the TUN interface can be persisted.

This method returns true if the TUN interface may be persisted – rolled into a new session with properties unchanged. This method is invoked only after all other tests for persistence allowability succeed; therefore, it has the ability to veto the persistence.

If persistence is ultimately enabled, tun_builder_establish_lite() will be called. Otherwise, tun_builder_establish() will be called.

Returns: true if the tun interface can be persisted, false otherwise

Definition at line 379 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_reroute_gw()

virtual bool openvpn::TunBuilderBase::tun_builder_reroute_gw	(	bool	ipv4,
		bool	ipv6,
		unsigned int	flags
	)

inlinevirtual

Callback to reroute the default gateway to the VPN interface.

This function is used to add the default route for either IPv4, IPv6, or both. It is called only once per TunBuilder session.

Parameters

ipv4	Set to `true` if the default route to be added should be IPv4.
ipv6	Set to `true` if the default route to be added should be IPv6.
flags	Additional flags defined in RGWFlags (see rgwflags.hpp for details).

Returns: true if the rerouting was successful, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 139 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_allow_family()

virtual bool openvpn::TunBuilderBase::tun_builder_set_allow_family	(	int	af,
		bool	allow
	)

inlinevirtual

Indicates whether traffic of a certain address family (AF_INET or AF_INET6) should be blocked or allowed.

This is used to prevent unencrypted packet leakage when the tunnel is IPv4-only or IPv6-only, but the local machine has connectivity with the other protocol to the internet.

This setting is controlled by the "block-ipv6" and "block-ipv6" configuration variables. If addresses are added for a family, this setting should be ignored for that family.

Remarks: See also Android's VPNService.Builder::allowFamily method.

Parameters

af	The address family (AF_INET or AF_INET6).
allow	A boolean indicating whether the address family should be allowed.

Returns: true if it was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 329 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_allow_local_dns()

virtual bool openvpn::TunBuilderBase::tun_builder_set_allow_local_dns ( bool allow )

inlinevirtual

Optional callback that indicates whether local DNS traffic should be blocked or allowed to prevent DNS queries from leaking while the tunnel is connected.

Note that this option is only relevant on Windows when the --dns option is used. If DNS is set via --dhcp-option, port 53 is always blocked for backwards compatibility reasons.

Parameters

allow Determines whether to allow (true) or block (false) local DNS traffic.

Returns: true if it was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 347 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_dns_options()

virtual bool openvpn::TunBuilderBase::tun_builder_set_dns_options ( const DnsOptions & dns )

inlinevirtual

Callback to set DNS related options to VPN interface.

Unlike others, this function is called only once and overrides when called multiple times.

Parameters

dns	A reference to the DnsOptions object containing the DNS options.

Returns: true if the DNS options were successfully added, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 195 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_layer()

virtual bool openvpn::TunBuilderBase::tun_builder_set_layer ( int layer )

inlinevirtual

Optional callback that indicates OSI layer to be used.

This function sets the OSI layer to be used. Possible values are 2 (TAP), 3 (TUN) or 0. Currently, we only support 3 (TUN).

Parameters

layer The OSI layer to set, should be 2 (TAP), 3 (TUN) or 0. Currently only 3 (TUN) is supported.

Returns: true if the layer was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 67 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_mtu()

virtual bool openvpn::TunBuilderBase::tun_builder_set_mtu ( int mtu )

inlinevirtual

Callback to set the MTU of the VPN interface.

This function sets the Maximum Transmission Unit (MTU) of the virtual private network (VPN) interface. It's designed to be called not more than once per TunBuilder session.

Parameters

mtu	The MTU size to set.

Returns: Returns true if the MTU was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 211 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_proxy_auto_config_url()

virtual bool openvpn::TunBuilderBase::tun_builder_set_proxy_auto_config_url ( const std::string & url )

inlinevirtual

Callback to set the proxy "Auto Config URL".

This function is a callback used to set the proxy "Auto Config URL". It is never called more than once per TunBuilder session.

Parameters

url	The URL string for the proxy autoconfiguration.

Returns: Returns true if the proxy auto config URL was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 255 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_proxy_http()

virtual bool openvpn::TunBuilderBase::tun_builder_set_proxy_http	(	const std::string &	host,
		int	port
	)

inlinevirtual

Callback to set the HTTP proxy.

This function acts as a callback to configure the HTTP proxy settings. It is never called more than once per TunBuilder session.

Parameters

host	The hostname or IP address of the HTTP proxy.
port	The port number of the HTTP proxy.

Returns: Returns true if the HTTP proxy was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 271 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_proxy_https()

virtual bool openvpn::TunBuilderBase::tun_builder_set_proxy_https	(	const std::string &	host,
		int	port
	)

inlinevirtual

Set the HTTPS proxy for the TunBuilder session.

This method sets the HTTPS proxy using the given host and port. It is called at most once during a TunBuilder session.

Parameters

host	The hostname of the HTTPS proxy.
port	The port number of the HTTPS proxy.

Returns: true if the HTTPS proxy was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 287 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_remote_address()

virtual bool openvpn::TunBuilderBase::tun_builder_set_remote_address	(	const std::string &	address,
		bool	ipv6
	)

inlinevirtual

Callback to set the address of the remote server.

This function is invoked to set the remote server's address. It will not be called more than once in a single TunBuilder session.

Parameters

address	Specifies the address of the remote server.
ipv6	Boolean indicating whether the given address is an IPv6 address.

Returns: true if the address was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture, and unittests::TunBuilderMock.

Definition at line 83 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_route_metric_default()

virtual bool openvpn::TunBuilderBase::tun_builder_set_route_metric_default ( int metric )

inlinevirtual

Optional callback to set default value for route metric.

This method is guaranteed to be called before other methods that deal with routes, such as tun_builder_add_route() and tun_builder_reroute_gw(). The route metric is ignored if its value is less than 0.

Parameters

metric The metric value to set for the route.

Returns: true if the route metric was successfully set

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 122 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_set_session_name()

virtual bool openvpn::TunBuilderBase::tun_builder_set_session_name ( const std::string & name )

inlinevirtual

Sets the session name for the TunBuilder.

This function is a callback that sets the session name. It is guaranteed to be called no more than once per TunBuilder session.

Parameters

name	A string representing the session name.

Returns: Returns true if the session name was successfully set, false otherwise

Reimplemented in openvpn::TunBuilderCapture.

Definition at line 226 of file base.hpp.

Here is the caller graph for this function:

◆ tun_builder_teardown()

virtual void openvpn::TunBuilderBase::tun_builder_teardown ( bool disconnect )

inlinevirtual

Indicates that tunnel is being torn down.

This function is called to indicate that the tunnel is being torn down.

Parameters

disconnect If true, the teardown is occurring prior to the final disconnect.

Definition at line 417 of file base.hpp.

Here is the caller graph for this function:

The documentation for this class was generated from the following file:

openvpn/tun/builder/base.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~TunBuilderBase()

Member Function Documentation

◆ tun_builder_add_address()

◆ tun_builder_add_proxy_bypass()

◆ tun_builder_add_route()

◆ tun_builder_add_wins_server()

◆ tun_builder_establish()

◆ tun_builder_establish_lite()

◆ tun_builder_exclude_route()

◆ tun_builder_get_local_networks()

◆ tun_builder_new()

◆ tun_builder_persist()

◆ tun_builder_reroute_gw()

◆ tun_builder_set_allow_family()

◆ tun_builder_set_allow_local_dns()

◆ tun_builder_set_dns_options()

◆ tun_builder_set_layer()

◆ tun_builder_set_mtu()

◆ tun_builder_set_proxy_auto_config_url()

◆ tun_builder_set_proxy_http()

◆ tun_builder_set_proxy_https()

◆ tun_builder_set_remote_address()

◆ tun_builder_set_route_metric_default()

◆ tun_builder_set_session_name()

◆ tun_builder_teardown()