Skip to content

Latest commit

 

History

History
151 lines (111 loc) · 6.41 KB

README.md

File metadata and controls

151 lines (111 loc) · 6.41 KB
Raw

Dealdoh

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.

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

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

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.

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

References