Skip to content
This repository has been archived by the owner on Aug 3, 2021. It is now read-only.

facebookarchive/doh-proxy

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.

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.