-
David Fifield
committed
4 years ago
1 parent ebb82e62
Revision indexing in progress... (symbol navigation in revisions will be accurate after indexed)
-
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 [email protected] 229 + -
1 + .\" https://man.openbsd.org/mdoc.7 2 + .Dd 2020-08-30 3 + .Dt DNSTT-SERVER 1 4 + .Os 5 + 6 + 7 + .Sh NAME 8 + 9 + .Nm dnstt-server 10 + .Nd DNS tunnel server 11 + 12 + 13 + .Sh SYNOPSIS 14 + 15 + .Nm 16 + .Fl gen-key 17 + .Op Fl privkey-file Ar FILENAME 18 + .Op Fl pubkey-file Ar FILENAME 19 + 20 + .Nm 21 + .Fl udp Ar ADDR : Ns Ar PORT 22 + .Op Fl privkey Ar HEX | Fl privkey-file Ar FILENAME 23 + .Op Fl mtu Ar MTU 24 + .Ar DOMAIN 25 + .Ar UPSTREAMADDR : Ns Ar UPSTREAMPORT 26 + 27 + 28 + .Sh DESCRIPTION 29 + 30 + .Nm 31 + is the server portion of a DNS tunnel. 32 + It receives DNS over UDP messages at 33 + .Ar ADDR : Ns Ar PORT , 34 + decodes the streams they contain, 35 + and forwards the streams as TCP connections to 36 + .Ar UPSTREAMADDR : Ns Ar UPSTREAMPORT . 37 + .Nm acts as the authoritative name server for 38 + .Ar DOMAIN 39 + and communicates with an instance of 40 + .Xr dnstt-client 1 41 + via a recursive resolver. 42 + 43 + .Ss GENERATING A SERVER KEYPAIR 44 + 45 + The tunnel client 46 + encrypts and authenticates the tunneled connection 47 + using the server's public key. 48 + To generate a server keypair, use the 49 + .Fl gen-key 50 + option. 51 + Use the 52 + .Fl privkey-file 53 + and 54 + .Fl pubkey-file 55 + options to save the generated private key, 56 + public key, or both, 57 + to a file. 58 + 59 + .Bl -tag 60 + 61 + .It Fl gen-key 62 + Generate a server keypair. 63 + 64 + .It Fl privkey-file Ar FILENAME 65 + With 66 + .Fl gen-key , 67 + save the generated private key to 68 + .Ar FILENAME . 69 + 70 + .It Fl pubkey-file Ar FILENAME 71 + With 72 + .Fl gen-key , 73 + save the generated public key to 74 + .Ar FILENAME . 75 + 76 + .El 77 + 78 + .Pp 79 + On the server, you only need to store the private key, because 80 + .Nm 81 + can derive the public key from the private key. 82 + The client only needs to have the server's public key 83 + and should not know the servers private key. 84 + 85 + .Ss RUNNING THE SERVER 86 + 87 + The required 88 + .Fl udp 89 + option specifies the UDP address on which 90 + .Nm 91 + listens for incoming DNS messages. 92 + 93 + .Bl -tag 94 + .It Fl udp Ar ADDR : Ns Ar PORT 95 + Accept DNS messages at the given address. 96 + .Ar PORT 97 + must typically be 53 98 + when operating with a recursive intermediate resolver, 99 + unless you have made some other provision for forwarding 100 + port 53 to 101 + .Ar PORT . 102 + 103 + .El 104 + 105 + .Pp 106 + Specify the server's persistent keypair using the 107 + .Fl privkey 108 + or 109 + .Fl privkey-file 110 + options. 111 + If you do not use one of these options, 112 + .Nm 113 + generates a temporary keypair 114 + and logs the public key to standard error. 115 + 116 + .Bl -tag 117 + 118 + .It Fl privkey Ar HEX 119 + .Ar HEX 120 + is a string of 64 hexadecimal digits. 121 + 122 + .It Fl privkey-file Ar FILENAME 123 + .Ar FILENAME 124 + is the name of a file containing 125 + 64 hexadecimal digits and an 126 + optional training newline character. 127 + 128 + .El 129 + 130 + .Pp 131 + In some situations, you may have to use the 132 + .Fl mtu 133 + option to control the maximum UDP payload size. 134 + 135 + .Bl -tag 136 + 137 + .It Fl mtu Ar MTU 138 + Never send UDP payloads larger than 139 + .Ar MTU 140 + bytes. 141 + The default 142 + .Ar MTU 143 + is 1232, but some recursive resolver only support a maximum of 512. 144 + You will know you need to use the 145 + .Fl mtu 146 + option when you see messages like this on standard error: 147 + .Dl FORMERR: requestor payload size 512 is too small (minimum 1232) 148 + 149 + .El 150 + 151 + 152 + .Sh EXAMPLES 153 + 154 + Generate a keypair. 155 + Save the private key to the file 156 + .Cm server.key 157 + and the public key to 158 + .Cm server.pub . 159 + Next, you would typically copy 160 + .Pa server.pub 161 + to the client. 162 + 163 + .Bd -literal -offset indent 164 + dnstt-server -gen-key -privkey-file server.key -pubkey-file server.pub 165 + .Ed 166 + 167 + .Pp 168 + Accept DNS messages at the UDP address 169 + .Cm 0.0.0.0:53 , 170 + decode the streams contained therein, 171 + and forward the streams as TCP connections to 172 + .Cm 127.0.0.1:8000 . 173 + Read the private key from the file 174 + .Cm server.key 175 + and derive the public key from it. 176 + The server should be configured to be 177 + the authoritative name server for the domain 178 + .Cm t.example.com . 179 + 180 + .Bd -literal -offset indent 181 + dnstt-server -udp 127.0.0.1:53 -privkey-file server.key t.example.com 127.0.0.1:8000 182 + .Ed 183 + 184 + 185 + .Sh DIAGNOSTICS 186 + 187 + .Nm 188 + writes running logs to standard error. 189 + 190 + At startup, 191 + .Nm 192 + logs its public key. 193 + This string can be used with the 194 + .Fl -pubkey 195 + option in 196 + .Xr dnstt-client 1 . 197 + 198 + .Dl pubkey 14ca15f53660e248d289d9302f992c4bee518f2361d6343dafa7b417b5a3d752 199 + 200 + .Pp 201 + At startup, 202 + .Nm 203 + logs the amount of useful payload capacity that can be stored 204 + in each DNS response, after accounting for the overhead of encoding. 205 + This number will vary depending on the length of 206 + .Ar DOMAIN 207 + and the value of 208 + .Ar MTU . 209 + 210 + .Dl effective MTU 932 211 + 212 + 213 + .Pp 214 + If the recursive resolver's stated maximum UDP payload size 215 + is smaller than 216 + .Ar MTU , 217 + .Nm 218 + will log a message like this, 219 + which tells you that you need to use the 220 + .Fl mtu 221 + option. 222 + 223 + .Dl FORMERR: requestor payload size 512 is too small (minimum 1232) 224 + 225 + 226 + .Sh SEE ALSO 227 + 228 + .Xr dnstt-client 1 229 + 230 + .Lk https://www.bamsoftware.com/software/dnstt/ 231 + 232 + 233 + .Sh AUTHORS 234 + 235 + .An David Fifield Aq Mt [email protected] 236 +