This tool is for penetration testing only. Never use a DNS resolver connected to the Internet on your IS.
Our VPN infrastructure is hosted on the Amazon EC2 & OVH clouds
open-source software: Java server, Flex client for Adobe AIR and Perl client are available on GitHub
Here is the official user's manual about the VPN-over-DNS Perl client. Follow those step-by-step instructions to explore the many features available with VPN-over-DNS.
Before being able to use this manual, you need to first install Perl and the VPN-over-DNS Perl client as described here.
In case you would like to install the Perl client without having any Internet access, here is a hack to bootstrap the installation using only DNS queries! Useful when you can access really nothing but dig (or nslookup) and a Perl runtime, not even root-level permission.
[ Now also available on Docker Hub: fenyoa/vpnoverdns ]
Table of contents
1- User account
become a registered user or use an anonymous account
2- Channel forwarding
forward a given local TCP port on the local host to the given host and port on a remote side
3- Tunneling
one command to simultaneously setup the DNS tunnel in a background process and attach the ssh command to your controlling terminal
4- Reverse channel forwarding
listening on a remote TCP port and forwarding the data to a local port on the local host
5- Using a web proxy
browse web servers by proxifying a local port to one of the free proxies offered by VPN-over-DNS
6- Configuring mail settings
steps to configure your mail provider login and password credentials
7- Reading mails
download and display your latest messages
8- Sending mails
write a new mail and send it through your mail provider
9- Running faster
running two times faster using "IN TXT" RRs instead of "IN A" ones
10- Whispering
speaking silently
11- Adding a background noise
add fuzzy useless requests to decrease signal-to-noise ratio
12- Debugging
watch every steps, at the DNS request/response layer
13- Fine tuning
make experiments and see behaviour changes, modifying low-level protocol parameters
Usage, parameters, options
The VPN-over-DNS Perl client is an open source GPL-licensed free software. It is made of only one file: vpnoverdns.pl. On this page, you will discover the many activities you can do with it. Note that two types of command-line switches can be used: parameters and options. Only one parameter can be used at a time, when launching vpnoverdns.pl in order to select a specific action (channel forwarding, mail management, ...). Many options can be used simultaneously, with one parameter. Some options are available only when using some specific parameters, others can be used any time. Depending on their meaning, parameters and options may or may not be followed by a string or number. Using the [-h|--help] parameter, you can get a full list of available options and parameters. Most of them are described in the following sections.
User account
The very first operation you need to do with the client is to associate with a VPN-over-DNS server account. During the association process, a unique user identifier (uuid) is stored in a file, in order to be re-used at the beginning of further operations: ${HOME}/.vpnoverdns.
The client can be associated to an anonymous user, or to a registered user. Depending on the type of account, you will have access to distinct operations:
To associate with an anonymous account, use the [-A|--anonymous] parameter and run the following command:
#
To associate with a registered user account, use the [-i|--initialize] parameter run the following command, that establishes an SSL/TLS session to the server farm, on top of a DNS tunnel (SSL/TLS is needed to protect the password privacy):
uuid=34809330
saving uuid to file /root/.vpnoverdns
#
Different error types can occur during the association to a registered user. First, your Perl installation may have not been recently updated with fresh root certificate autorities (you should get an error message like this one: SSL upgrade failed: SSL connect attempt failed with unknown error error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate). Or your Perl installation may only contain an old version of the LWP::UserAgent module, that have difficulties to verify certificates through proxified SSL/TLS sessions (you should get an error message like this one: can not verify SSL/TLS certificate, LWP version too old). In both of those cases, use [-n|--nocertcheck] option to get rid of the SSL/TLS server certificate validation step.
bad response: 500 SSL upgrade failed: SSL connect attempt failed with unknown error error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
retrying...
bad response: 500 Can't connect to 127.0.0.1:8081
retrying...
bad response: 500 Can't connect to 127.0.0.1:8081
retrying...
bad response: 500 Can't connect to 127.0.0.1:8081
retrying...
Problem with LWP::UserAgent perl module => see '-u' and '-A' parameters instead.
#
# perl vpnoverdns.pl -n -i username password
uuid=34809330
saving uuid to file /root/.vpnoverdns
#
Secondly, your Perl installation may lack of LWP::UserAgent, LWP::Protocol::https or XML::Simple, that are mandatory modules used by VPN-over-DNS to establish SSL communications and parse their content. In that case, directly register your uuid with the [-u|--uuid] parameter followed by your uuid, instead of fetching it with your username and password. You need to remember your personal uuid (get it right now from this form) and run the following command (replace uuid with your uuid, for instance 34809330 to follow the previous example):
#
Finally, your host may already have a process listening on port TCP/8081.This port is used internally by the Perl client when using the [-i|--initialize] parameter. So, in such a case, you need to change this port with the [-p|--port] option:
can not bind to port 8081: Address already in use - try using -p option
18127: bad response: 500 Server closed connection without sending any data back
retrying...
18127: bad response: 500 Server closed connection without sending any data back
retrying...
18127: bad response: 500 Server closed connection without sending any data back
retrying...
18127: bad response: 500 Server closed connection without sending any data back
retrying...
Problem with LWP::UserAgent perl module => see '-u' and '-A' options instead.
#
# perl vpnoverdns.pl -p 8082 -i username password
uuid=34809330
saving uuid to file /root/.vpnoverdns
#
Channel forwarding
Now that you are a registered user or have associated the client with an anonymous account, your can use the Perl client to forward a given local TCP port on the local host to the given host and port on a remote side. The channel is encapsulated on top of DNS queries to the VPN-over-DNS server farm and is joined to a TCP connection to the remote host/port. This works by allocating a socket to listen to port on the local side, optionally bound to the specified bind_address. Whenever a connection is made to this port, the client forks a new background process that connects to the server farm, asking to be joined to a new TCP connection established with the remote host/port. Use the [-L|--local] parameter followed by the optional bind address, the local port, the remote host and the remote port according to the following template: -L [bind_address:]port:host:hostport. If you do not specify a bind address, only local connections can be done to the local port. If you specify a bind address corresponding to a local interface connected to some network, connections from remote hosts to this address will be possible. If you do not specify any bind address but use the [-g|--global] option, the Perl client will listen on every interfaces and remote connections from remote hosts will be allowed to connect to local forwarded ports.
For example, listening on local port 2222 to proxify an SSH connection to an Internet server:
listening on port TCP/2222
connection from: 127.0.0.1:50947
Last login: Wed Dec 16 14:19:45 2015
FreeBSD 10.2-RELEASE-p2 (MYKERNEL)
virt%
SSH tunneling
SSH tunneling can be done by launching simultaneously two shell commands, like the previous example. But you can do it more easily using only one command, asking the VPN-over-DNS client to setup the DNS tunnel in a background process and to execute the ssh command in the foreground. For this purpose, just specify the target hostname with the [-S|--ssh] parameter. Optionally, you can also specify some SSH parameters using the [-o|--sshoptions] option.
For example, connecting to a remote host and specifying a reverse X-Window tunnel:
Last login: Wed Dec 16 14:25:42 2015
FreeBSD 10.2-RELEASE-p2 (MYKERNEL)
virt% xeyes &
virt%
Your host may already have a process listening on port TCP/8081 and this port is used internally by the Perl client when using the [-S|--ssh] parameter. So, in such a case, you need to change this port with the [-p|--port] option:
can not bind to port 8081: Address already in use
ssh_exchange_identification: Connection closed by remote host
#
# perl -p 8082 vpnoverdns.pl -S fenyo.net
Last login: Wed Dec 16 14:25:42 2015
FreeBSD 10.2-RELEASE-p2 (MYKERNEL)
virt%
Reverse channel forwarding
To perform reverse channel forwarding (listening on a remote TCP port and forwarding the data to a local port on the local host), just use SSH forwarding with the -R SSH option and add an optional remote command with the [-C|--sshcommand] option of the VPN-over-DNS client.
For instance, to let remote users connect with telnet to your local host:
Using a web proxy
You can browse web servers by proxifying a local port to one of the free proxies offered by VPN-over-DNS:
listening on port TCP/8080
connection from: 127.0.0.1:50952
# lynx http://www.wikipedia.org
You can use the [-X|--proxy] parameter as a shortcut to listen on local port TCP/3128 and redirect it to an open proxy depending on your account type (127.0.0.1:3128 for registered users and 127.0.0.1:3130 for anonymous users):
listening on port TCP/3128
connection from: 127.0.0.1:50972
# lynx http://www.wikipedia.org
Configuring mail settings
To configure your mail settings, you need to use the Android client, even if you only want to use the Perl client in the future. This procedure is required for the security of your credentials (see below).
Just follow those steps:
Some words about the security of your mail credentials:
For your security, your mail provider settings are not stored on the client side. Your mail settings include your mail provider, your login (usually your email address) and your password to connect to this mail provider. They allow the VPN-over-DNS server farm to authenticate to this mail provider. Here is the way they are protected:
Reading mails
You can download your mails using the [-c|--checkmails] parameter. Note that the mails are not erased from your mail provider. The Perl client first ask the VPN-over-DNS server to connect to your mail provider and download the latest new messages (use the [-v|--verbose] option to display the many steps involved in this process). This can take up to some minutes, depending on the number of new mails. When new mails have been downloaded, they are fetched by the client, that dipslays their content on the standard output.
As you can see, the number of new mails is first displayed:
1 new mail
-------------------------------------------------------------------------------
From: "Support [VPN-over-DNS]" <support@vpnoverdns.com>
To: "Alexandre Fenyo" <alex@fenyo.net>
Cc:
Subject: Welcome back on VPN-over-DNS!
Sent: 2015-12-20 08:46:28.0
Received: 2015-12-20 16:17:11.868
Please, connect on http://www.vpnoverdns.com/doc.html to get a full documentation on our free services.
#
Here is the output of same session, using the additional [-v|--verbose] option:
LWP::UserAgent version: 6.13
Net::DNS version: 0.68
Ask the server to check mails
The server is currently checking mails
The server is currently checking mails
1 new mail
-------------------------------------------------------------------------------
From: "Support [VPN-over-DNS]" <support@vpnoverdns.com>
To: "Alexandre Fenyo" <alex@fenyo.net>
Cc:
Subject: Welcome back on VPN-over-DNS!
Sent: 2015-12-20 08:46:28.0
Received: 2015-12-20 16:17:11.868
Please, connect on http://www.vpnoverdns.com/doc.html to get a full documentation on our free services.
#
If you have not previously configured your mail provider settings using the Android client, you will get the following error:
GetNMails error 11 (SRV2CLT_NO_ACCOUNT)
#
To get rid of this error message, you need to first configure your mail provider settings as explained in the previous section.
Sending mails
Before sending mails, you need to configure your mail account settings (see the above session Configuring mail settings). You can send a mail using the [-w|--sendmail] parameter. The client ask for the mail header fields content (From/To/Cc/Subject) and the body of your mail. At the end of the body, terminate the mail with EOF or a dot at the start of an empty line.
For instance, here is a way to send a mail to the Support Team:
To: support@vpnoverdns.com
Cc: alex@fenyo.net
Subject: Hi!
Enter the body and finish with EOF or a '.' at the start of an empty line
Many thanks for your OSS Perl client.
Sincerely,
Myself.
.
#
Running faster
By default, the Perl client does only use DNS ressource records of type IPv4 Address ("IN A" RRs, see RFC-1034 for more information). Downstream sessions can be about 2 times faster using "IN TXT" RRs. It's not the default behaviour because those requests can easily be filtered or detected. To use "IN TXT" RRs types, juste add the [-F|--fast] option on the command line. This option is available with every command line parameters that involve DNS queries (mail management, channel forwarding, named user registration, web proxifying...).
For example, connecting with SSH to a remote host using faster "IN TXT" RRs:
Last login: Wed Dec 16 17:22:22 2015
FreeBSD 10.2-RELEASE-p2 (MYKERNEL)
virt%
Whispering
The Perl client bursts out parallel DNS queries for fast data transfer. Sometimes, you do not want to be detected or to affect temporarily your resolver performances. Two optional switches can then help you in such situations:
For example, connecting with SSH in silent mode and using only 2 parallel queries at a time:
Last login: Wed Dec 16 18:11:42 2015
FreeBSD 10.2-RELEASE-p2 (MYKERNEL)
virt%
Adding a background noise
Being detected often depends on the signal-to-noise ratio. We have seen previously how to lower the signal, let's see now how to increase the noise. This can be done using the option [-f|--fuzzy] followed by the number of fuzzy useless requests sent between two valid ones. Those requests have similarities with the valid ones but are directed to domains whose names are built by appending randomly words and TLDs chosen in dictionnaries included in the Perl client. You can mix together [-f|--fuzzy], [-s|--silent], [-P|--parallel] and [-F|--fast] options as you like, with any parameter of your choice (channel forwarding, mail management, ...). Of course, it is useless to select those options with a parameter that does not generate DNS queries like [-A|--anonymous] or [-u|--uuid] for instance.
For example, connecting with SSH while sending 5 fuzzy requests between a pair of valid ones:
Last login: Wed Dec 16 18:15:42 2015
FreeBSD 10.2-RELEASE-p2 (MYKERNEL)
virt%
Debugging
Two levels of verbosity can be selected using the [-v|--verbose] option and the [-d|--debug] option. The latter implies the former. The latter displays every DNS packets received or sent and the different high-level protocol messages.
For example, connecting with SSH in debug mode:
sending message: 34809330§GetMessage
1 parallel query
background query sent for sz-00000021.rn-63458508.id-00000001.v2.tun.vpnoverdns.com: try 1
1 pending query - 0 answer received
waiting for responses during 1.00001001358032 s
timeout reached for sz-00000021.rn-63458508.id-00000001.v2.tun.vpnoverdns.com: try 1
background query sent for sz-00000021.rn-63458508.id-00000001.v2.tun.vpnoverdns.com: try 2
1 pending query - 0 answer received
waiting for responses during 2.00001406669617 s
background response for sz-00000021.rn-63458508.id-00000001.v2.tun.vpnoverdns.com: try 2
one RR of type A
parallel queries completed
1 parallel query
background query sent for rn-66442184.bf-003132333435363737c2a74765744d657373616765.wr-00000000.id-11866403.v2.tun.vpnoverdns.com: try 1
1 pending query - 0 answer received
#
You can estimate the average DNS round-trip-time between your host and the VPN-over-DNS server farm using the [-r|--rtt] parameter followed by the number of requests to send for the test. For instance, to compute the RTT with 5 requests, just launch the following command:
>>> send ping request, waiting for 1 byte
>>> response received in 0.0319509506225586 s
>>> send ping request, waiting for 2 bytes
>>> response received in 0.0290169715881348 s
>>> send ping request, waiting for 3 bytes
>>> response received in 0.0289311408996582 s
>>> send ping request, waiting for 4 bytes
>>> response received in 0.0289859771728516 s
>>> send ping request, waiting for 5 bytes
>>> response received in 0.0290789604187012 s
failed requests: 0 / 5 (0%)
average rtt for non failed requests: 0.0246606667836507 s
#
Fine tuning
The DNS tunneling protocol implemented by the VPN-over-DNS clients and the server farm makes use of some technical parameters whose values should provide the best user experience. In some cases, advanced users can try to modify these values to fine-tune the protocol and get better performances. Here are some options used to modify the default values (each of these options must be followed by a number).
[-m|--maxwrite]:
New mobile app from the same developer See our new amazing app for iOS: WiFi Map Explorer
Server and clients are now open-source: GPLv3 Explore the source tree on GitHub