Awesome
DNS Over HTTPS Proxy
A set of python 3 scripts that supports proxying DNS over HTTPS as specified in the IETF Draft draft-ietf-doh-dns-over-https.
DOH provides a way to run encrypted DNS over HTTPS, a protocol which can freely traverse firewalls when other encrypted mechanism may be blocked.
The project comes with a set of 4 tools:
- doh-proxy: A service that receives DOH queries over HTTP2 and forwards them to a recursive resolver.
- doh-httpproxy: Like
doh-proxy
but uses HTTP instead of HTTP2. The main intent is to run this behind a reverse proxy. - doh-stub: A service that listens for DNS queries and forwards them to a DOH server.
- doh-client: A tool to perform a test DNS query against DOH server.
See the CONTRIBUTING
file for how to help out.
DOH Proxy was created during IETF Hackathon 100 as a proof-of-concept and is not used at Facebook.
You are welcome to use it, but be aware that support is limited and best-effort.
Installing
To install an already packaged version directly from PyPi:
$ pip3 install doh-proxy
Usage
doh-proxy
doh-proxy
is a stand alone server answering DOH request. The proxy does not do
DNS recursion itself and rather forward the query to a full-featured DNS
recursive server or DNS caching server.
By running doh-proxy
, you can get and end-to-end DOH solution with minimal
setup.
$ sudo doh-proxy \
--upstream-resolver=::1 \
--certfile=./fullchain.pem \
--keyfile=./privkey.pem
doh-httpproxy
doh-httpproxy
is designed to be running behind a reverse proxy. In this setup
a reverse proxy such as NGINX would be handling the
HTTPS/HTTP2 requests from the DOH clients and will forward them to
doh-httpproxy
backends.
While this setup requires more upfront setup, it allows running DOH proxy unprivileged and on multiple cores.
$ doh-httpproxy \
--upstream-resolver=::1 \
--port 8080 \
--listen-address ::1
doh-httpproxy
now also supports TLS, that you can enable passing the
args --certfile
and --keyfile
(just like doh-proxy
)
doh-stub
doh-stub
is the piece of software that you would run on the clients. By
providing a local DNS server, doh-stub
will forward the DNS requests it
receives to a DOH server using an encrypted link.
You can start a stub resolver with:
$ doh-stub \
--listen-port 5553 \
--listen-address ::1 \
--domain foo.bar \
--remote-address ::1
and query it.
$ dig @::1 -p 5553 example.com
doh-client
doh-client
is just a test cli that can be used to quickly send a request to
a DOH server and dump the returned answer.
$ doh-client \
--domain dns.dnsoverhttps.net \
--qname sigfail.verteiltesysteme.net \
--dnssec
id 37762
opcode QUERY
rcode SERVFAIL
flags QR RD RA
edns 0
eflags DO
payload 4096
;QUESTION
sigfail.verteiltesysteme.net. IN AAAA
;ANSWER
;AUTHORITY
;ADDITIONAL
$ doh-client \
--domain dns.dnsoverhttps.net \
--qname sigok.verteiltesysteme.net \
--dnssec
id 49772
opcode QUERY
rcode NOERROR
flags QR RD RA AD
edns 0
eflags DO
payload 4096
;QUESTION
sigok.verteiltesysteme.net. IN AAAA
;ANSWER
sigok.verteiltesysteme.net. 60 IN AAAA 2001:638:501:8efc::139
sigok.verteiltesysteme.net. 60 IN RRSIG AAAA 5 3 60 20180130030002 20171031030002 30665 verteiltesysteme.net. O7QgNZFBu3fULvBXwM39apv5nMehh51f mLOVEsC8qZUyxIbxo4eDLQt0JvPoPpFH 5TbWdlm/jxq5x2/Kjw7yUdpohhiNmdoD Op7Y+RyHbf676FoC5Zko9uOAB7Pp8ERz qiT0QPt1ec12bM0XKQigfp+2Hy9wUuSN QmAzXS2s75k=
;AUTHORITY
;ADDITIONAL
Development
Requirements
- python >= 3.5
- aiohttp
- aioh2
- dnspython
Building
DOH Proxy uses Python'setuptools to manage dependencies and build.
To install its dependencies:
$ python3 setup.py develop
# Due to GH #63
$ pip install git+https://github.com/URenko/aioh2#egg=aioh2
To build:
$ python3 setup.py build
To run unittests:
$ python3 setup.py test
To run the linter:
DOH Proxy uses GitHub Action Super-Linter to lint the code. In order to validate your code locally, it is possible to run Super-Linter locally using the following comand line from within the repository:
docker run -e RUN_LOCAL=true -e VALIDATE_PYTHON_PYLINT=false \
-e FILTER_REGX_INCLUDE='(dohproxy|test)/.*.py' \
-v $(pwd):/tmp/lint \
--rm github/super-linter:v3
From within the root of the repository, you can test the proxy, stub and client respectively by using the following commands:
$ sudo PYTHONPATH=. ./dohproxy/proxy.py ...
$ PYTHONPATH=. ./dohproxy/httpproxy.py ...
$ PYTHONPATH=. ./dohproxy/stub.py ...
$ PYTHONPATH=. ./dohproxy/client.py ...
License
DOH Proxy is BSD-licensed.