Skip to content
Powerful DNS-over-HTTPS proxy & client written in PHP.
Branch: master
Clone or download
Latest commit 1e74ddf Jul 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Jun 1, 2019
examples Added PSR-15 support Jun 20, 2019
src Added exception for invalid dns message for better error handling Jun 20, 2019
tests/Unit Added PSR-15 support Jun 20, 2019
.gitignore
.travis.yml Merge static code analysis in one unique stage Jun 5, 2019
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jun 1, 2019
CONTRIBUTING.md Added CONTRIBUTING guidelines Jun 1, 2019
LICENSE.md Make better README Jun 1, 2019
README.md Update README.md Jul 13, 2019
composer.json Added PSR-15 support Jun 20, 2019
phpunit.xml.dist Fixed composer.json, change typo in phpunit configuration, fixed type… Jun 19, 2019

README.md

Dealdoh

A toy to deal DNS over HTTPS and more!

Dealdoh is a powerful DNS-over-HTTPS (DoH) proxy server written in PHP.

It can be use as a DoH proxy server or a client.

Dealdoh also attempts to provide a low-level abstraction layer for DNS messaging.

PHP from Packagist Build Status codecov Scrutinizer code quality (GitHub/Bitbucket) Packagist

Description

Dealdoh can be use in different manners and for different purposes. It attempts to achieve the following goals:

  • provide a DoH middleware PSR-15 compliant which can be use in any PHP application to act as a DNS proxy server.
  • provide a variety of DNS stub resolver.
  • provide a large panel of DNS clients.
  • provide a low-level abstraction layer for development around DNS.

Dealdoh also comes with a dealdoh-client embedding the following features:

  • an application implementing Dealdoh middleware and ready to be run as a micro-service.
  • a DNS CLI client to make DNS queries, configure DNS upstreams, etc...

Features

  • Provide a DoH proxy server which can be simply plug as a middleware on any PHP 7.3 application. Only require a web-server.
  • Create and forward DNS messages in different format to different type of DNS upstream resolvers.
  • Use a pool of DNS upstream resolvers to send queries with a fallback mechanism.
  • Compatible with a variety of DNS protocols: RFC-1035 (TCP/UDP), RFC-8484 (DoH), Google DoH API.
  • Provide a DNS low-level abstraction layer for DNS development.
  • Make DNS query from the command-line and provide results in JSON

Roadmap

  • Improve robustness and compliance of current DNS clients
  • Ability to choose a DNS upstream fallback/selection strategy
  • Good documentation

Getting started

If you wish to get started quickly, you might want to use dealdoh-client which offers a ready-to-use implementation.

Requirements

  • PHP 7.3
  • Web server
  • HTTPS enabled with valid certificates (self-signed certificates can work but it depends of the DOH client)

To get trusted certificates in a local environment, I recommend you to use mkcert which generate for you a local Certificate Authority, and create locally trusted certificates with it. Take 3 minutes to check its really simple documentation for your OS. (since installation differs on each OS)

Installation

  • Install Dealdoh as a dependency:

composer require noglitchyo/dealdoh

As stated before, DohProxy::forward() method consumes PSR-7 ServerRequest to make the integration easier.

The example below illustrates how to use two DNS upstream resolvers which are using different protocols. In this example, the used protocols are TCP/UDP (RFC-1035) and DoH (RFC-8484). Two types of DNS client who can handle each of the DNS protocols used by our upstreams are injected to handle those upstreams.

<?php
$dnsMessageFactory = new \NoGlitchYo\Dealdoh\Factory\Dns\MessageFactory();
$dnsResolver = new \NoGlitchYo\Dealdoh\Service\DnsPoolResolver(
    new \NoGlitchYo\Dealdoh\Entity\DnsUpstreamPool([
        'dns://8.8.8.8:53',
        'https://cloudflare-dns.com/dns-query',
    ]),
    [
        new \NoGlitchYo\Dealdoh\Client\DohClient(
            new \Http\Adapter\Guzzle6\Client(new \GuzzleHttp\Client()),
            $dnsMessageFactory
        ),
        new \NoGlitchYo\Dealdoh\Client\StdClient(
            new \Socket\Raw\Factory(), 
            $dnsMessageFactory
        ),
    ]
);

$dnsProxy = new \NoGlitchYo\Dealdoh\DohProxy(
    $dnsResolver,
    $dnsMessageFactory,
    new \NoGlitchYo\Dealdoh\Factory\DohHttpMessageFactory($dnsMessageFactory)
);

/** @var $response \Psr\Http\Message\ResponseInterface */
$response = $dnsProxy->forward(/* Expect a \Psr\Http\Message\RequestInterface object */);
  • Testing the installation

First, be aware that usually, DoH client/server will send/receive DNS requests on the following path: /dns-query as recommended in RFC-8484. Make sure your Dealdoh's entrypoint has been configured to listen on this route or configure your client accordingly if it is possible.

A large variety of client already exists than you can easily find on Internet. For testing purpose, I advise the one below:

To make it easier, I created a Docker image that you can directly pull and run by running:

docker run --name dohfb -it noglitchyo/facebookexperimental-doh-proxy doh-client --domain <DEALDOH_ENTRYPOINT> --qname google.com --dnssec --insecure

Replace the <DEALDOH_ENTRYPOINT> with the host of your entrypoint for Dealdoh.

(Tips: pass the --insecure option to doh-client if you are using self-signed certificates #notDocumented)

Please, check how to use the client.

  • Using client from Web Browser

Mozilla Firefox provides a Trusted Recursive Resolver who can be configured to query DoH servers.

I advise you to read this really good article from Daniel Stenberg which will give you lot of details about this TRR and how to configure it like a pro.

Please check the browser implementations list.

Examples

Checkout some really simple integration examples to get a glimpse on how it can be done:

Testing

If you wish to run the test, checkout the project and run the test with:

composer test

Contributing

Get started here CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Why Dealdoh?

Dealdoh was created for development purpose. I wanted to reach my Docker containers from the browser by their hostnames. So I started to use a Docker image who discover services and register their hostname into a DNS exposed on port 53. But I encountered the following issues:

  • I could not change the /etc/hosts file
  • I could not change the DNS for my computer (restrictions issue)

I ended up with the following solution: use the DoH client from Firefox and proxy every DNS query to a DoH proxy: Dealdoh.

Acknowledgments

References

You can’t perform that action at this time.