A proof of concept DNS-Over-HTTPS proxy implementing https://datatracker.ietf.org/doc/draft-ietf-doh-dns-over-https/

Clone this repo:
  1. 8622150 remove jekyll version pinning from Gemfile by chantra · 1 year, 6 months ago master
  2. 3f768b4 rebuild pages by chantra · 1 year, 6 months ago
  3. 46bc626 Force commit to rebuild GH pages by chantra · 1 year, 6 months ago
  4. 110005b dummy commit to force GH page rebuild by chantra · 1 year, 8 months ago
  5. 4678a4d Merge pull request #102 from chantra/tcp_timeout by chantra · 1 year, 8 months ago

DNS Over HTTPS Proxy

Test Code Base GitHub Super-Linter PyPI version

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.


To install an already packaged version directly from PyPi:

$ pip3 install 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 \


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 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 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 \
id 37762
opcode QUERY
flags QR RD RA
edns 0
eflags DO
payload 4096
sigfail.verteiltesysteme.net. IN AAAA

$ doh-client  \
    --domain dns.dnsoverhttps.net \
    --qname sigok.verteiltesysteme.net \
id 49772
opcode QUERY
flags QR RD RA AD
edns 0
eflags DO
payload 4096
sigok.verteiltesysteme.net. IN AAAA
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=



  • python >= 3.5
  • aiohttp
  • aioh2
  • dnspython


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 ...


DOH Proxy is BSD-licensed.