mirror of
https://github.com/tladesignz/dnstt.git
synced 2026-09-28 09:58:04 +03:00
229 lines
4.7 KiB
Groff
229 lines
4.7 KiB
Groff
.\" 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
|