man/dnstt-client.1

   1 .\" https://man.openbsd.org/mdoc.7
   2 .Dd 2020-08-30
   3 .Dt DNSTT-CLIENT 1
   4 .Os
   5
   6
   7 .Sh NAME
   8
   9 .Nm dnstt-client
  10 .Nd DNS tunnel client
  11
  12
  13 .Sh SYNOPSIS
  14
  15 .Nm
  16 .Op Fl doh Ar URL | Fl dot Ar HOST : Ns Ar PORT | Fl udp Ar HOST : Ns Ar PORT
  17 .Op Fl pubkey Ar HEX | Fl pubkey-file Ar FILENAME
  18 .Ar DOMAIN
  19 .Ar LOCALADDR : Ns Ar LOCALPORT
  20
  21
  22 .Sh DESCRIPTION
  23
  24 .Nm
  25 is the client portion of a DNS tunnel.
  26 It receives TCP connections at
  27 .Ar LOCALADDR : Ns Ar LOCALPORT
  28 and forwards them,
  29 encoded as a sequence of DNS messages
  30 and via a recursive resolver,
  31 to an instance of
  32 .Xr dnstt-server 1
  33 running as the authoritative name server for
  34 .Ar DOMAIN .
  35 The DNS messages may be carried over
  36 DNS over HTTPS,
  37 DNS over TLS,
  38 or classical DNS over UDP.
  39
  40 .Pp
  41 You must use exactly one of the
  42 .Fl doh ,
  43 .Fl dot ,
  44 or
  45 .Fl udp
  46 options,
  47 to specify what form of DNS to use:
  48
  49 .Bl -tag
  50
  51 .It Fl doh Ar URL
  52 Use DNS over HTTPS.
  53 .Ar URL
  54 is the URL of the DNS over HTTPS resolver,
  55 including the
  56 .Ql /dns-query
  57 path if used by the resolver.
  58
  59 .Pp
  60 See
  61 .Lk https://github.com/curl/curl/wiki/DNS-over-HTTPS#publicly-available-servers
  62 for a list of public DNS over HTTPS resolvers.
  63
  64 .It Fl dot Ar HOST : Ns Ar PORT
  65 Use DNS over TLS.
  66 .Ar HOST
  67 and
  68 .Ar PORT
  69 are the TCP address of the DNS over TLS resolver.
  70 .Ar PORT
  71 is normally 853.
  72
  73 .Pp
  74 See
  75 .Lk https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Public+Resolvers#DNSPrivacyPublicResolvers-DNS-over-TLS%28DoT%29
  76 for a list of public DNS over TLS resolvers.
  77
  78 .It Fl udp Ar HOST : Ns Ar PORT
  79 Use DNS over UDP.
  80 .Ar HOST
  81 and
  82 .Ar PORT
  83 are the UDP address of the DNS resolver.
  84 .Ar PORT
  85 is normally 53.
  86
  87 With
  88 .Fl udp ,
  89 you have the option of communicating directly with an instance of
  90 .Xr dnstt-server 1 ,
  91 without going through a recursive resolver.
  92 That is,
  93 .Ar HOST : Ns Ar PORT
  94 may point directly at the authoritative name server for
  95 .Ar DOMAIN ,
  96 where
  97 .Xr dnstt-server 1
  98 is running.
  99
 100 .El
 101
 102 .Pp
 103 In addition, you must use one of the
 104 .Fl pubkey
 105 or
 106 .Fl pubkey-file
 107 options to specify the public key used
 108 for authenticating the server and encrypting the channel.
 109 The public key should have been generated by
 110 .Ql dnstt-server -gen-key .
 111 .Xr dnstt-server 1
 112 prints its public key at the beginning of its log output.
 113
 114 .Bl -tag
 115
 116 .It Fl pubkey Ar HEX
 117 .Ar HEX
 118 is a string of 64 hexadecimal digits.
 119
 120 .It Fl pubkey-file Ar FILENAME
 121 .Ar FILENAME
 122 is the name of a file containing
 123 64 hexadecimal digits and an
 124 optional training newline character.
 125
 126 .El
 127
 128 .Sh EXAMPLES
 129
 130 Tunnel through the DNS over HTTPS resolver at
 131 .Cm https://resolver.example/dns-query
 132 to the authoritative name server for
 133 .Cm t.example.com .
 134 Listen locally at
 135 .Cm 127.0.0.1:7000
 136 for connections to forward through the tunnel.
 137 Use the server public key stored in the file
 138 .Cm server.pub .
 139
 140 .Bd -literal -offset indent
 141 dnstt-client -doh https://resolver.example/dns-query -pubkey-file server.pub t.example.com 127.0.0.1:7000
 142 .Ed
 143
 144 .Pp
 145 Tunnel through the DNS over TLS resolver at
 146 .Cm resolver.example:853
 147 to the authoritative name server for
 148 .Cm t.example.com .
 149 Listen locally at
 150 .Cm 127.0.0.1:7000
 151 for connections to forward through the tunnel.
 152 Use the given hex string as the server public key.
 153
 154 .Bd -literal -offset indent
 155 dnstt-client -dot resolver.example:853 -pubkey 14ca15f53660e248d289d9302f992c4bee518f2361d6343dafa7b417b5a3d752 t.example.com 127.0.0.1:7000
 156 .Ed
 157
 158
 159 .Sh DIAGNOSTICS
 160
 161 .Nm
 162 writes running logs to standard error.
 163
 164 At startup,
 165 .Nm
 166 logs the amount of useful payload capacity that can be stored
 167 in each DNS query, after accounting for the overhead of encoding.
 168 This number will vary depending on the length of
 169 .Ar DOMAIN .
 170
 171 .Dl effective MTU 128
 172
 173
 174 .Sh BUGS
 175
 176 .Nm
 177 has a distinctive TLS fingerprint
 178 and is probably easy to block on that basis.
 179
 180
 181 .Sh SECURITY CONSIDERATIONS
 182
 183 The
 184 .Fl udp
 185 option is not covert,
 186 and is intended for debugging and special configurations.
 187 Only the
 188 .Fl doh
 189 and
 190 .Fl dot
 191 modes provide protection against detection of the tunnel,
 192 because they encrypt DNS messages between
 193 .Nm
 194 and the recursive resolver.
 195 The
 196 .Fl udp
 197 mode sends plaintext DNS messages,
 198 which reveal the use of a DNS tunnel by their special format.
 199
 200 Even with
 201 .Fl doh
 202 or
 203 .Fl dot ,
 204 it may be possible for an observer to infer
 205 the use of a tunnel
 206 by traffic metadata features such as
 207 traffic volume and timing.
 208 The recursive resolver can see the plaintext of DNS messages
 209 and is always in a position to easily detect the use of a tunnel.
 210
 211 But even if the use of a tunnel is detected, the
 212 .Em contents
 213 of the tunnel remain encrypted and authenticated.
 214 The end-to-end encryption and authentication of the tunnel is a separate layer,
 215 independent of the encryption
 216 provided by DNS over HTTPS or DNS over TLS.
 217
 218
 219 .Sh SEE ALSO
 220
 221 .Xr dnstt-server 1
 222
 223 .Lk https://www.bamsoftware.com/software/dnstt/
 224
 225
 226 .Sh AUTHORS
 227
 228 .An David Fifield Aq Mt david@bamsoftware.com