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
 129 .Sh OPTIONS
 130
 131
 132 .Bl -tag
 133
 134 .It Fl utls Oo
 135 .Op Ar weight Ns Sy * Ns
 136 .Ar label
 137 .Oc Ns Op , Ns ...
 138 Set the weighted distribution of TLS fingerprints.
 139
 140 .Pp
 141 .Nm
 142 uses
 143 .Lk https://github.com/refraction-networking/utls "uTLS"
 144 to disguise its TLS fingerprint.
 145 By default, a fingerprint is selected randomly from a weighted distribution.
 146 You can control the distribution using the
 147 .Fl utls
 148 option, which takes an argument of a comma-separated
 149 list of fingerprint labels,
 150 each optionally preceded by an integer weight and
 151 .Sy * .
 152 If a weight is omitted, it is taken to be 1.
 153
 154 .Pp
 155 Examples:
 156 .Bl -item -offset indent -compact
 157 .It
 158 -utls '3*Firefox,2*Chrome,1*iOS'
 159 .It
 160 -utls Firefox
 161 .It
 162 -utls random
 163 .It
 164 -utls none
 165 .El
 166
 167 .Pp
 168 Use the
 169 .Fl help
 170 option to see the default distribution
 171 and the set of available fingerprint labels.
 172 The special value
 173 .Cm random
 174 stands for a randomized fingerprint.
 175 The special value
 176 .Cm none
 177 disables uTLS and uses the native Go crypto/tls fingerprint.
 178
 179 .It Fl help
 180 Describes command line usage.
 181 Shows the default value of
 182 .Fl utls
 183 and the available TLS fingerprint labels.
 184
 185 .El
 186
 187
 188 .Sh EXAMPLES
 189
 190 Tunnel through the DNS over HTTPS resolver at
 191 .Cm https://resolver.example/dns-query
 192 to the authoritative name server for
 193 .Cm t.example.com .
 194 Listen locally at
 195 .Cm 127.0.0.1:7000
 196 for connections to forward through the tunnel.
 197 Use the server public key stored in the file
 198 .Cm server.pub .
 199
 200 .Bd -literal -offset indent
 201 dnstt-client -doh https://resolver.example/dns-query -pubkey-file server.pub t.example.com 127.0.0.1:7000
 202 .Ed
 203
 204 .Pp
 205 Tunnel through the DNS over TLS resolver at
 206 .Cm resolver.example:853
 207 to the authoritative name server for
 208 .Cm t.example.com .
 209 Listen locally at
 210 .Cm 127.0.0.1:7000
 211 for connections to forward through the tunnel.
 212 Use the given hex string as the server public key.
 213
 214 .Bd -literal -offset indent
 215 dnstt-client -dot resolver.example:853 -pubkey 14ca15f53660e248d289d9302f992c4bee518f2361d6343dafa7b417b5a3d752 t.example.com 127.0.0.1:7000
 216 .Ed
 217
 218
 219 .Sh DIAGNOSTICS
 220
 221 .Nm
 222 writes running logs to standard error.
 223
 224 At startup,
 225 .Nm
 226 logs the amount of useful payload capacity that can be stored
 227 in each DNS query, after accounting for the overhead of encoding.
 228 This number will vary depending on the length of
 229 .Ar DOMAIN .
 230
 231 .Dl effective MTU 128
 232
 233
 234 .Sh SECURITY CONSIDERATIONS
 235
 236 The
 237 .Fl udp
 238 option is not covert,
 239 and is intended for debugging and special configurations.
 240 Only the
 241 .Fl doh
 242 and
 243 .Fl dot
 244 modes provide protection against detection of the tunnel,
 245 because they encrypt DNS messages between
 246 .Nm
 247 and the recursive resolver.
 248 The
 249 .Fl udp
 250 mode sends plaintext DNS messages,
 251 which reveal the use of a DNS tunnel by their special format.
 252
 253 Even with
 254 .Fl doh
 255 or
 256 .Fl dot ,
 257 it may be possible for an observer to infer
 258 the use of a tunnel
 259 by traffic metadata features such as
 260 traffic volume and timing.
 261 The recursive resolver can see the plaintext of DNS messages
 262 and is always in a position to easily detect the use of a tunnel.
 263
 264 But even if the use of a tunnel is detected, the
 265 .Em contents
 266 of the tunnel remain encrypted and authenticated.
 267 The end-to-end encryption and authentication of the tunnel is a separate layer,
 268 independent of the encryption
 269 provided by DNS over HTTPS or DNS over TLS.
 270
 271
 272 .Sh SEE ALSO
 273
 274 .Xr dnstt-server 1
 275
 276 .Lk https://www.bamsoftware.com/software/dnstt/
 277
 278
 279 .Sh AUTHORS
 280
 281 .An David Fifield Aq Mt david@bamsoftware.com