Skip to main content

A client and proxy implementation of

Project description

DNS Over HTTPS Proxy

Build Status 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 \
    --remote-address ::1

and query it.

$ dig @::1 -p 5553


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 \
    --qname \
id 37762
opcode QUERY
flags QR RD RA
edns 0
eflags DO
payload 4096

$ doh-client  \
    --domain \
    --qname \
id 49772
opcode QUERY
flags QR RD RA AD
edns 0
eflags DO
payload 4096
;ANSWER 60 IN AAAA 2001:638:501:8efc::139 60 IN RRSIG AAAA 5 3 60 20180130030002 20171031030002 30665 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 develop

To build:

$ python3 build

To run unittests:

$ python3 test

To run the linter:

$ python3 flake8
# Also run flake8 on the testing files
$ flake8 test

From within the root of the repository, you can test the proxy, stub and client respectively by using the following commands:

$ sudo PYTHONPATH=. ./dohproxy/ ...
$ PYTHONPATH=. ./dohproxy/ ...
$ PYTHONPATH=. ./dohproxy/ ...
$ PYTHONPATH=. ./dohproxy/ ...


DOH Proxy is BSD-licensed.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

doh-proxy-0.0.9.tar.gz (27.6 kB view hashes)

Uploaded source

Built Distribution

doh_proxy-0.0.9-py3-none-any.whl (23.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page