.\" https://man.openbsd.org/mdoc.7
.Dd 2020-08-30
.Dt DNSTT-CLIENT 1
.Os


.Sh NAME

.Nm dnstt-client
.Nd DNS tunnel client


.Sh SYNOPSIS

.Nm
.Op Fl doh Ar URL | Fl dot Ar HOST : Ns Ar PORT | Fl udp Ar HOST : Ns Ar PORT
.Op Fl pubkey Ar HEX | Fl pubkey-file Ar FILENAME
.Ar DOMAIN
.Ar LOCALADDR : Ns Ar LOCALPORT


.Sh DESCRIPTION

.Nm
is the client portion of a DNS tunnel.
It receives TCP connections at
.Ar LOCALADDR : Ns Ar LOCALPORT
and forwards them,
encoded as a sequence of DNS messages
and via a recursive resolver,
to an instance of
.Xr dnstt-server 1
running as the authoritative name server for
.Ar DOMAIN .
The DNS messages may be carried over
DNS over HTTPS,
DNS over TLS,
or classical DNS over UDP.

.Pp
You must use exactly one of the
.Fl doh ,
.Fl dot ,
or
.Fl udp
options,
to specify what form of DNS to use:

.Bl -tag

.It Fl doh Ar URL
Use DNS over HTTPS.
.Ar URL
is the URL of the DNS over HTTPS resolver,
including the 
.Ql /dns-query
path if used by the resolver.

.Pp
See
.Lk https://github.com/curl/curl/wiki/DNS-over-HTTPS#publicly-available-servers
for a list of public DNS over HTTPS resolvers.

.It Fl dot Ar HOST : Ns Ar PORT
Use DNS over TLS.
.Ar HOST
and
.Ar PORT
are the TCP address of the DNS over TLS resolver.
.Ar PORT
is normally 853.

.Pp
See
.Lk https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Public+Resolvers#DNSPrivacyPublicResolvers-DNS-over-TLS%28DoT%29
for a list of public DNS over TLS resolvers.

.It Fl udp Ar HOST : Ns Ar PORT
Use DNS over UDP.
.Ar HOST
and
.Ar PORT
are the UDP address of the DNS resolver.
.Ar PORT
is normally 53.

With
.Fl udp ,
you have the option of communicating directly with an instance of
.Xr dnstt-server 1 ,
without going through a recursive resolver.
That is,
.Ar HOST : Ns Ar PORT
may point directly at the authoritative name server for
.Ar DOMAIN ,
where
.Xr dnstt-server 1
is running.

.El

.Pp
In addition, you must use one of the
.Fl pubkey
or
.Fl pubkey-file
options to specify the public key used
for authenticating the server and encrypting the channel.
The public key should have been generated by
.Ql dnstt-server -gen-key .
.Xr dnstt-server 1
prints its public key at the beginning of its log output.

.Bl -tag

.It Fl pubkey Ar HEX
.Ar HEX
is a string of 64 hexadecimal digits.

.It Fl pubkey-file Ar FILENAME
.Ar FILENAME
is the name of a file containing
64 hexadecimal digits and an
optional training newline character.

.El

.Sh EXAMPLES

Tunnel through the DNS over HTTPS resolver at
.Cm https://resolver.example/dns-query
to the authoritative name server for
.Cm t.example.com .
Listen locally at
.Cm 127.0.0.1:7000
for connections to forward through the tunnel.
Use the server public key stored in the file
.Cm server.pub .

.Bd -literal -offset indent
dnstt-client -doh https://resolver.example/dns-query -pubkey-file server.pub t.example.com 127.0.0.1:7000
.Ed

.Pp
Tunnel through the DNS over TLS resolver at
.Cm resolver.example:853
to the authoritative name server for
.Cm t.example.com .
Listen locally at
.Cm 127.0.0.1:7000
for connections to forward through the tunnel.
Use the given hex string as the server public key.

.Bd -literal -offset indent
dnstt-client -dot resolver.example:853 -pubkey 14ca15f53660e248d289d9302f992c4bee518f2361d6343dafa7b417b5a3d752 t.example.com 127.0.0.1:7000
.Ed


.Sh DIAGNOSTICS

.Nm
writes running logs to standard error.

At startup,
.Nm
logs the amount of useful payload capacity that can be stored
in each DNS query, after accounting for the overhead of encoding.
This number will vary depending on the length of
.Ar DOMAIN .

.Dl effective MTU 128


.Sh BUGS

.Nm
has a distinctive TLS fingerprint
and is probably easy to block on that basis.


.Sh SECURITY CONSIDERATIONS

The
.Fl udp
option is not covert,
and is intended for debugging and special configurations.
Only the
.Fl doh
and
.Fl dot
modes provide protection against detection of the tunnel,
because they encrypt DNS messages between
.Nm
and the recursive resolver.
The
.Fl udp
mode sends plaintext DNS messages,
which reveal the use of a DNS tunnel by their special format.

Even with
.Fl doh
or
.Fl dot ,
it may be possible for an observer to infer
the use of a tunnel
by traffic metadata features such as
traffic volume and timing.
The recursive resolver can see the plaintext of DNS messages
and is always in a position to easily detect the use of a tunnel.

But even if the use of a tunnel is detected, the 
.Em contents
of the tunnel remain encrypted and authenticated.
The end-to-end encryption and authentication of the tunnel is a separate layer,
independent of the encryption
provided by DNS over HTTPS or DNS over TLS.


.Sh SEE ALSO

.Xr dnstt-server 1

.Lk https://www.bamsoftware.com/software/dnstt/


.Sh AUTHORS

.An David Fifield Aq Mt david@bamsoftware.com