noglitchyo / dealdoh
A simple DNS over HTTPS proxy built on PHP.
Requires
- php: ^7.3
- ext-json: *
- ext-sockets: *
- clue/socket-raw: ^1.4
- nyholm/psr7: ^1.1
- php-http/guzzle6-adapter: ^2.0
- psr/http-client: *
- psr/http-server-middleware: ^1.0
- psr/log: ^1.1
- react/dns: ^1.3.0
Requires (Dev)
- mockery/mockery: ^1.2
- monolog/monolog: ^1.24
- phpstan/phpstan: ^0.11.8
- phpunit/phpunit: ^8.1
- react/datagram: ^1.5
- squizlabs/php_codesniffer: 3.*
- symfony/process: ^5.1
This package is auto-updated.
Last update: 2024-10-29 05:40:17 UTC
README
Play with DNS over HTTPS and much more!
Dealdoh is a DNS-over-HTTPS (DoH) proxy and a library around DNS messaging written in PHP.
Overview
This library gives ability to proxy DoH requests and/or to send DNS queries with standard UDP/TCP and various modern and secure DNS protocols like DNSCrypt, DNS-over-HTTPS (DoH), GoogleDNS.
It attempts to achieve the following goals:
- provide high-compatibility with a large variety of DNS protocols.
- provide a well-designed abstraction layer for development around DNS in PHP.
Features
- DoH proxy middleware PSR-15/PSR-7 compliant.
- Create and forward DNS messages to different type of DNS upstream resolvers.
- Forward DNS query through multiple DNS upstream resolvers.
- Compatible with DNS protocols: RFC-1035 (Plain DNS over TCP/UDP), RFC-8484 (DoH), Google DoH API, DNSCrypt
- Abstraction layer around DNS development.
- Parse DNS stamps
Client
dealdoh-client is a CLI utility which offers a ready-to-use implementation of this library to send and forward DNS queries.
Library
Requirements
- PHP 7.3
- Web server
- Optional: HTTPS enabled with valid certificates (self-signed certificates can work but it depends of the DOH client making the queries)
Installation
-
Run
composer require noglitchyo/dealdoh
-
DohResolverMiddleware::forward()
method consumes PSR-7 ServerRequest. Some compatible implementations which can be used:- https://github.com/Nyholm/psr7 -
composer require nyholm/psr7
- https://github.com/guzzle/psr7 -
composer require guzzle/psr7
- https://github.com/zendframework/zend-diactoros -
composer require zendframework/zend-diactoros
- https://github.com/Nyholm/psr7 -
-
Configure your application to call
DohResolverMiddleware::forward()
-
Testing the installation
As recommended in RFC-8484, usually, DoH client/server will send/receive DNS requests on the path: /dns-query
.
Your application should be configured to listen on this route.
A large variety of DoH client exists than can be used to test the installation.
-
Using client from Web Browser
Mozilla Firefox provides a Trusted Recursive Resolver who can be configured to query DoH servers. This article from Daniel Stenberg provides a lot of details about TRR and how to configure it. Please check also the browser implementations list.
Example
<?php use GuzzleHttp\Client as GuzzleClient; use Http\Adapter\Guzzle6\Client as GuzzleClientAdapter; use NoGlitchYo\Dealdoh\Dns\Client\DnsCryptClient; use NoGlitchYo\Dealdoh\Dns\Client\DohClient; use NoGlitchYo\Dealdoh\Dns\Client\PlainDnsClient; use NoGlitchYo\Dealdoh\Dns\Resolver\DnsUpstreamPoolResolver; use NoGlitchYo\Dealdoh\Entity\DnsUpstreamPool; use NoGlitchYo\Dealdoh\Mapper\DnsCrypt\AuthenticatedEncryptionMapper; use NoGlitchYo\Dealdoh\Mapper\HttpResponseMapper; use NoGlitchYo\Dealdoh\Mapper\MessageMapper; use NoGlitchYo\Dealdoh\Middleware\DohResolverMiddleware; use NoGlitchYo\Dealdoh\Repository\DnsCrypt\CertificateRepository; use Psr\Http\Message\ResponseInterface; $messageMapper = new MessageMapper(); // Initialize the DNS clients to use with the resolver $dnsClients = [ new DohClient(new GuzzleClientAdapter(new GuzzleClient()), $messageMapper), new PlainDnsClient($messageMapper), new DnsCryptClient(new AuthenticatedEncryptionMapper(), new CertificateRepository(), $messageMapper) ]; // Initialize the list of DNS upstreams to use to resolve the DNS queries $dnsUpstreamPool = new DnsUpstreamPool([ 'dns://8.8.8.8:53', 'https://cloudflare-dns.com/dns-query', 'sdns://AQcAAAAAAAAAFlsyMDAxOmJjODoxODI0OjczODo6MV0gAyfzz5J-mV9G-yOB4Hwcdk7yX12EQs5Iva7kV3oGtlEgMi5kbnNjcnlwdC1jZXJ0LmFjc2Fjc2FyLWFtcy5jb20', ]); // Initialize the DNS resolver with the list of upstreams and the list of clients able to exchange with the upstreams $dnsResolver = new DnsUpstreamPoolResolver($dnsUpstreamPool, $dnsClients); // Create the ResolverMiddleware with the created DnsResolver $dohMiddleware = new DohResolverMiddleware($dnsResolver, $messageMapper, new HttpResponseMapper($messageMapper)); /** @var $response ResponseInterface */ $response = $dohMiddleware->forward(/* Expect a \Psr\Http\Message\RequestInterface object */);
More 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
Acknowledgments
- https://github.com/reactphp/dns
- https://github.com/mageddo/dns-proxy-server
- https://github.com/facebookexperimental/doh-proxy
- https://github.com/DNSCrypt/dnscrypt-proxy