DNSSEC

The DNSSEC component adds full DNSSEC validation to DNS resolution. It is a standalone package (php-standard-library/dnssec) that requires a Psl\DNS\ResolverInterface instance from the psl/dns package.

DNSSEC validation verifies that DNS responses have not been tampered with by checking cryptographic signatures (RRSIG), walking trust chains from the DNS root (DS/DNSKEY), and validating authenticated denial of existence proofs (NSEC/NSEC3).

Getting Started

To use DNSSEC, you need two things: a DNS resolver that requests DNSSEC records (dnssec: true), and the DNSSEC validation layer that wraps it.

use Psl\DNS;
use Psl\DNS\Record\RecordType;
use Psl\DNSSEC;

// Create a DNSSEC-validating resolver
$inner = new DNS\SystemResolver(dnssec: true);
$trustChain = new DNSSEC\TrustChainResolver($inner);
$resolver = new DNSSEC\SecureResolver($inner, $trustChain);

// Queries are validated: signatures, trust chain, NSEC proofs
$response = $resolver->query('example.com', RecordType::A);

// Throws SignatureFailedException, BrokenTrustChainException,
// InvalidProofException, or UnsignedResponseException on failure

RRSIG: Signature Verification

Every DNSSEC-signed response includes RRSIG records alongside the answer records. Each RRSIG contains a cryptographic signature over a set of records, the signer's identity, and the key tag to locate the corresponding DNSKEY.

When SecureResolver receives a response, it verifies that the RRSIG signatures are valid using the zone's public keys (DNSKEY records). If any signature is invalid or expired, SignatureFailedException is thrown.

DS/DNSKEY: Trust Chain

DNSSEC trust is established through a chain from the DNS root to the target zone. Each parent zone contains a DS (Delegation Signer) record that is a cryptographic hash of the child zone's DNSKEY. By verifying each link in the chain, TrustChainResolver proves that the zone's keys are authorized by the parent, all the way up to the root trust anchor.

The walk for example.com goes: root (.) DNSKEY > com. DS > com. DNSKEY > example.com. DS > example.com. DNSKEY.

NSEC/NSEC3: Authenticated Denial

When a domain does not exist (NXDOMAIN), the server must prove it. NSEC records list the names that DO exist in sorted order, proving there is no name between them. NSEC3 records do the same but with hashed names to prevent zone enumeration.

SecureResolver validates these proofs automatically. If the proof is missing or invalid, InvalidProofException is thrown.

Trust Anchors

TrustChainResolver uses the IANA root KSK as its trust anchor by default. For fully offline environments, StaticTrustChainResolver accepts pre-loaded DNSKEY records per zone, bypassing all network queries for trust chain resolution.

use Psl\DateTime\Duration;
use Psl\DNS;
use Psl\DNS\DNSSEC\Algorithm;
use Psl\DNS\Record\DNSKEYRecord;
use Psl\DNSSEC;

$inner = new DNS\SystemResolver(dnssec: true);

// Default: uses IANA root KSK, walks the DS/DNSKEY chain via DNS queries
$trustChain = new DNSSEC\TrustChainResolver($inner);

// Fully offline: pre-loaded DNSKEY records per zone, no network queries
$rootDnskey = new DNSKEYRecord('.', Duration::seconds(0), 257, 3, Algorithm::RSASHA256, '...');
$comDnskey = new DNSKEYRecord('com.', Duration::seconds(0), 257, 3, Algorithm::ECDSAP256SHA256, '...');

$offline = new DNSSEC\StaticTrustChainResolver([
    '.' => [$rootDnskey],
    'com.' => [$comDnskey],
]);

$resolver = new DNSSEC\SecureResolver($inner, $trustChain);

Validation Errors

DNSSEC validation produces specific exceptions for each failure mode:

All exceptions extend Psl\DNSSEC\Exception\RuntimeException.

Caching

DNSSEC validation is expensive - each query triggers a trust chain walk from the root zone through every intermediate zone to the target. CachedTrustChainResolver caches the validated trust chain results so subsequent queries to the same TLD reuse the cached chain. Combine with CachedResolver on top to cache the final validated responses.

use Psl\Cache;
use Psl\DNS;
use Psl\DNS\Record\RecordType;
use Psl\DNSSEC;

$cache = new Cache\LocalStore();

// The inner resolver must request DNSSEC records
$dnsResolver = new DNS\SystemResolver(dnssec: true);

// Cache trust chain results to avoid repeated root-to-leaf walks
// Without caching, every query triggers DS/DNSKEY lookups for each zone
$trustChain = new DNSSEC\CachedTrustChainResolver(new DNSSEC\TrustChainResolver($dnsResolver), $cache);

// SecureResolver validates every response using the cached trust chain
$secureResolver = new DNSSEC\SecureResolver($dnsResolver, $trustChain);

// Cache the validated DNS responses on top
$resolver = new DNS\CachedResolver($secureResolver, $cache);

// First query: full trust chain walk (root -> com. -> example.com.)
$resolver->query('example.com', RecordType::A);

// Second query for same TLD: trust chain for "com." is cached
$resolver->query('another.com', RecordType::A);

// Third query for same domain: entire response is cached
$resolver->query('example.com', RecordType::A);

Kitchen Sink

Compose DNSSEC validation with static entries, hosts file, search domains, split-horizon routing, multiple racing DNS-over-TLS nameservers, and caching. DNSSEC validation only wraps the public DNS path; trusted sources (static, internal, hosts file) are outside the validation boundary.

use Psl\Cache;
use Psl\DateTime\Duration;
use Psl\DNS;
use Psl\DNS\Record\ARecord;
use Psl\DNS\Record\RecordType;
use Psl\DNS\System\HostsFile\HostsFile;
use Psl\DNSSEC;
use Psl\IO;
use Psl\IP\Address;
use Psl\TCP;
use Psl\TLS;

$cache = new Cache\LocalStore();

// 1. Static entries (trusted by definition, no DNSSEC needed)
$static = new DNS\StaticResolver([
    'db.internal' => [
        RecordType::A->value => [
            new ARecord('db.internal', Duration::hours(999), Address::parse('10.0.0.5')),
        ],
    ],
    'cache.internal' => [
        RecordType::A->value => [
            new ARecord('cache.internal', Duration::hours(999), Address::parse('10.0.0.6')),
        ],
    ],
]);

// 2. Internal nameserver for corporate domains (trusted network, no DNSSEC)
$internalDns = new DNS\FallbackResolver([
    new DNS\UDPResolver('10.0.0.53'),
    new DNS\TCPResolver('10.0.0.53'),
]);

// 3. Race multiple DNSSEC-enabled public nameservers
$public = new DNS\RacingResolver([
    // Cloudflare DNS-over-TLS
    new DNS\FallbackResolver([
        new DNS\UDPResolver('1.1.1.1', dnssec: true),
        new DNS\TCPResolver(
            '1.1.1.1',
            port: 853,
            dnssec: true,
            connector: new TLS\TCPConnector(new TCP\Connector(), new TLS\Connector(new TLS\ClientConfiguration())),
        ),
    ]),
    // Google DNS-over-TLS
    new DNS\FallbackResolver([
        new DNS\UDPResolver('8.8.8.8', dnssec: true),
        new DNS\TCPResolver(
            '8.8.8.8',
            port: 853,
            dnssec: true,
            connector: new TLS\TCPConnector(new TCP\Connector(), new TLS\Connector(new TLS\ClientConfiguration())),
        ),
    ]),
    // Cloudflare secondary (plain TCP fallback)
    new DNS\FallbackResolver([
        new DNS\UDPResolver('1.0.0.1', dnssec: true),
        new DNS\TCPResolver('1.0.0.1', dnssec: true),
    ]),
    // Google secondary (plain TCP fallback)
    new DNS\FallbackResolver([
        new DNS\UDPResolver('8.8.4.4', dnssec: true),
        new DNS\TCPResolver('8.8.4.4', dnssec: true),
    ]),
]);

// 4. DNSSEC: validate public DNS responses only
$public = new DNSSEC\SecureResolver(
    $public,
    new DNSSEC\CachedTrustChainResolver(new DNSSEC\TrustChainResolver($public), $cache),
);

// 5. Static overrides first, then DNSSEC-validated public DNS
$base = new DNS\FallbackResolver([$static, $public]);

// 6. Route corporate domains to internal DNS (unvalidated),
//    everything else to static + DNSSEC-validated public
$routed = new DNS\SplitHorizonResolver(routes: [
    new DNS\Route(['corp.internal', 'dev.internal'], $internalDns),
], default: $base);

// 7. Expand short names using search domains
$searched = new DNS\SearchDomainResolver($routed, ['corp.internal', 'dev.internal']);

// 8. Check the hosts file before any network query
$hostsAware = new DNS\HostsFileResolver($searched, HostsFile::load());

// 9. Cache everything on top
$resolver = new DNS\CachedResolver($hostsAware, $cache);

// 10. Profit!
$response = $resolver->query('php-standard-library.dev', RecordType::A);

IO\write_line(
    'php-standard-library.dev -> %s',
    $response->getFirstAnswerRecord(ARecord::class)?->address->toString() ?? '<unknown>',
);

Supported Algorithms

RFC Compliance

See src/Psl/DNSSEC/ for the full API.