Hide.me CLI VPN client for Linux

Hide.me CLI is a VPN client for use with eVenture Ltd. Hide.me VPN service based on the WireGuard protocol. Client's features include:

• Completely standalone solution which does not depend on any external binaries or tools
• Key exchange via RESTful requests secured with TLS 1.3
• TLS certificate pinning of server's certificates to defeat man-in-the-middle sort of attacks
• Dead peer detection
• Leak protection a.k.a. kill-switch based on routing subsystem
• Mobility/Roaming support
• DNS management
• IPv6 support
• systemd notification support
• Split tunneling
• DNS filter (SmartGuard)

TODO:

• Server lists and server chooser
• Automatic server selection
• Client certificate authentication/authorization

Build

You may clone this repository and run:

go build -o hide.me

Alternatively, download the latest build from the releases section.

Installation (Manual)

Source tree and binary releases contain simple installation and uninstallation scripts. Hide.me CLI gets installed in /opt/hide.me directory. Apart from copying hide.me files to /opt/hide.me no modifications to the system are done.<br> When systemd based distribution is detected the installer links a template unit file which can be used to instantiate connections.

Installation (ArchLinux Package)

You can build the package using the PKGBUILD provided in packaging/archlinux/ (requires git clone --recurse-submodules) or from https://aur.archlinux.org/packages/hide-client/

To build:

makepkg && sudo pacman -U hide-client-0.9.12-1-any.pkg.tar.zst 

Note that the ArchLinux package changes the default locations of the installed files to /usr/bin/hide.me for the binary, /etc/hide.me/accessToken.txt for the accessToken, /usr/share/hide.me/CA.pem for the certificate and /usr/lib/systemd/system/hide.me@service for the systemd unit.

Hide.me WireGuard implementation details

WireGuard is one of the most secure and simplest VPN tunneling solutions in the industry. It is easy to set up and use as long as no WireGuard public key exchange over an insecure medium (such as Internet) is required. Any sort of WireGuard public key exchange is out of the scope of the WireGuard specification.

Key exchange

The complicated task of public key exchange and secret key negotiation over an insecure medium is, usually, being handled by:

• IKE protocol - a hard to understand, and a rather complicated part of IPSec
• TLS protocol - a foundation for HTTPS and virtually any other secure protocol

hide.me implementation of WireGuard leverages HTTPS (TLS) for the exchange of:

• WireGuard Public keys
• WireGuard Shared keys
• IP addressing information (IP addresses, DNS server addresses,gateways...)

Authentication for all operations requires the use of an Access-Token. An Access-Token is a just a binary blob which is cryptographically tied to a hide.me account.

Connection setup flow

Connection to a hide.me VPN server gets established in these steps:

1. hide.me CLI contacts a REST endpoint, over a secured channel, requesting a public key exchange and a server-side connection setup
2. Server authenticates the request, sets up the connection and serves the IP addressing information (including the WireGuard endpoint address). Server issues a randomized Session-Token which may be used to disconnect this particular session
3. hide.me CLI sets up a WireGuard peer according to the server's instruction and starts the DPD check loop

Leak protection

In contrast with many other solutions, hide.me CLI does not use any sort of Linux firewalling technology (IPTables, NFTables or eBPF). Instead of relying on Linux'es IP filtering frameworks, hide.me CLI selectively routes traffic by setting up a special routing table and a set of routing policy database rules. Blackhole routes in the aforementioned routing table drop all traffic unless it meets one of the following conditions:

• Traffic is local ( loopback interfaces, local broadcasts and IPv6 link-local multicast )
• DHCPv4 traffic
• Traffic is explicitly allowed by the means of the Split-tunneling option
• Traffic is about to be tunneled

This mode of operation makes it possible for the users to establish their own firewalling policies with which hide.me CLI won't interfere.

Usage

Usage instructions may be printed by running hide.me CLI without any parameters.

Usage:
  ./hide.me [options...] <command> [host]
...

Commands

hide.me CLI user interface is quite simple. There are just eight commands available:

command:
  token - request an Access-Token (required for connect)
  connect - connect to a vpn server
  conf - generate a configuration file to be used with the -c option
  categories - fetch and dump filtering category list
  service - run in remotely controlled service mode
  updateDoh - update DNS-over-HTTPs server list
  resolve - resolve host using DNS-over-HTTPs
  lookup - resolve host using DNS
  list - fetch the server list

To connect to a VPN server, an Access-Token must be requested from a VPN server. The token command issues an Access-Token request. An Access-Token issued by any server may be used, for authentication, with any other hide.me VPN server. When a server issues an Access-Token, that token must be stored in a file. The default filename for an Access-Token is "accessToken.txt".

Once an Access-Token is in place it may be used for connect requests. Stale access tokens get updated automatically.

hide.me CLI does not necessarily have to be invoked with a bunch of command line parameters. Instead, a YAML formatted configuration file may be used to specify all the options. To generate such a configuration file the conf command may be used.

For DNS filtering (SmartGuard), a list of filtering categories can be obtained with categories command

hide.me CLI can be run in service mode. When started in service mode, hide.me CLI just exposes a REST interface for control. The controller is responsible for configuring connections, activation of the kill-switch or any other operation. REST interface listen address is configurable through -caddr option.

Note that there are a few options which are configurable only through the configuration file. Such options are:

• Password - DANGEROUS, do not use this option unless you're aware of the security implications
• ConnectTimeout
• AccessTokenUpdateDelay

host:
  fqdn, short name or an IP address of a hide.me server
  Required when the configuration file does not contain it

The hostname of a hide.me REST endpoint may be specified as a fully qualified domain name (nl.hide.me), short name (nl) or an IP address. There's no guarantee that the REST endpoint will match a WireGuard endpoint.

DNS-over-HTTPS Implementation

hide.me CLI prioritizes DNS-over-HTTPS (DoH) for secure DNS resolution before falling back to regular DNS. This approach significantly enhances privacy and security when resolving domain names.

DoH Resolvers Management

hide.me CLI handles DoH resolvers in the following ways:

• Default Configuration: Without a resolvers.txt file, hide.me CLI relies on a small set of hardcoded DoH servers.

• Enhanced Configuration: The updateDoh command populates a resolvers.txt file with over 100 usable DoH servers.

• Security by Randomization: On each invocation, hide.me CLI automatically randomizes the order of DoH servers in the resolvers.txt file, ensuring that a different DoH server is used for each session.

File Format

The resolvers.txt file is a simple text file containing DNS stamps for each DoH server.

Testing DNS Resolution

hide.me CLI provides commands to test and compare different DNS resolution methods:

• resolve command: Test DNS-over-HTTPS resolution for a specific hostname.

• lookup command: Issue a regular DNS request, useful for comparing DoH responses with traditional DNS responses.

This approach not only secures DNS requests but distributes them across multiple providers, adding an additional layer of privacy protection to hide.me CLI's network operations.

Options

  -4    Use IPv4 tunneling only

Limit all IP protocol operations to IPv4. Even though the server will provide IPv4 and IPv6 addressing only IPv4 addresses, IPv4 rules and IPv4 routes get installed. Leak protection/kill-switch works for IPv4 traffic only. IPv6 traffic flow remains unsecured.

WARNING: This option degrades security and should be used only when it's safe to do so, e.g. when the client machine has it's IPv6 stack disabled. Please, do not use it otherwise because IPv6 leaks may happen.

  -6   	Use IPv6 tunneling only

Limit all IP protocol operations to IPv6. Even though the server will provide IPv4 and IPv6 addressing only IPv6 addresses, IPv6 rules and IPv6 routes get installed. Leak protection/kill-switch works for IPv6 traffic only. IPv4 traffic flow remains unsecured.

WARNING: This option degrades security and should not be used unless the client wishes to tunnel the IPv6 traffic only.

  -b filename
    	resolv.conf backup filename (default "")

Hide.me CLI keeps a backup of /etc/resolv.conf in memory. In addition to that backup hide.me CLI may back up /etc/resolv.conf to a file specified by this option.

  -c filename
    	Configuration filename

Use a configuration file named "filename".

  --ca string
    	CA certificate bundle (default "CA.pem")

During TLS negotiation the VPN server's certificate needs to be verified. This option makes it possible to specify an alternate CA certificate bundle file.

  --caddr address
    	Control interface listen address (default "@hide.me")

Set the service mode control interface listen address. hide.me CLI, by default, listens on an abstract UNIX socket hide.me

  --ccert certificate
    	Control interface certificate file

Set the service mode control interface X509 certificate in PEM f