Skip to content

Full Toolkit for Next-Level Domain Analysis

13.7 KB
Raw Blame
import type { Answer } from 'dns-packet';
import { describe, expect, it, vi } from 'vitest';

import { UserFacingError } from '@/lib/user-facing-error';

import { dsDigest } from './ds';
import {
  DsChainNameNotFoundError,
  type DsChainQuery,
  resolveDsChain,
  resolveDsChainWithin,
} from './ds-chain';
import { genKey, signDnskeyRrset } from './test-helpers';
import { ROOT_DNSKEY_RRSIG, ROOT_DNSKEYS, ROOT_NOW } from './test-vectors';
import { dnskeyKeyTag } from './wire';

// Every walk is judged at ROOT_NOW, inside the captured root signature's
// validity window. Zones below the root sign with one generated key.
const NOW = ROOT_NOW;
const DAY = 86_400;
const WINDOW = { inception: NOW - DAY, expiration: NOW + DAY };
type Signer = ReturnType<typeof genKey>;
const KSK = genKey(13);

const soa = (name: string): Answer => ({
  name,
  type: 'SOA',
  ttl: 60,
  data: {
    mname: `ns.${name}`,
    rname: `hostmaster.${name}`,
    serial: 1,
    refresh: 3600,
    retry: 600,
    expire: 86400,
    minimum: 60,
  },
});

// A delegation: the parent's NS RRset for a child zone cut.
const ns = (name: string): Answer => ({
  name,
  type: 'NS',
  ttl: 60,
  data: `ns.${name}`,
});

const host = (name: string): Answer => ({
  name,
  type: 'A',
  ttl: 60,
  data: '192.0.2.1',
});

const keyRecord = (name: string, key = KSK.dnskey): Answer => ({
  name,
  type: 'DNSKEY',
  ttl: 60,
  data: key,
});

// The RRSIG over a zone's DNSKEY RRset `keys`, made by `signer`.
const keySig = (
  name: string,
  keys = [KSK.dnskey],
  signer: Signer = KSK,
  window = WINDOW,
): Answer => ({
  name,
  type: 'RRSIG',
  ttl: 60,
  data: signDnskeyRrset(name, keys, signer, window),
});

const dsRecord = (
  name: string,
  key = KSK.dnskey,
  digestType = 2,
  corrupt = false,
): Answer => {
  // Digest types without a hash here (e.g. 3, GOST) get a SHA-256 stand-in.
  const digest = dsDigest(name, key, digestType) ?? dsDigest(name, key, 2)!;
  return {
    name,
    type: 'DS',
    ttl: 60,
    data: {
      keyTag: dnskeyKeyTag(key),
      algorithm: key.algorithm,
      digestType,
      digest: corrupt ? Buffer.alloc(digest.length) : digest,
    },
  };
};

// A delegated, signed zone apex whose parent publishes a matching DS.
const signedZone = (name: string): Answer[] => [
  ns(name),
  soa(name),
  keyRecord(name),
  dsRecord(name),
  keySig(name),
];

// com with its own SOA and validly signed KSK, under the parent DS `ds`.
const com = (...ds: Answer[]): Answer[] =>
  [root(), soa('com'), keyRecord('com'), keySig('com'), ...ds].flat();

// Answers like AuthoritativeResolver.resolveAnswers over a small DNS tree:
// a query returns the records its name owns, a name that owns nothing but
// has descendants is an empty non-terminal (NODATA), and anything else is
// NXDOMAIN. The zone is the deepest delegation (NS owner) at or above the
// name; DS is answered from the parent side of a cut.
const dnsTree =
  (records: Answer[]): DsChainQuery =>
  async (name, type) => {
    const labels = name === '.' ? [] : name.split('.');
    const zone =
      labels
        .map((_, i) => labels.slice(i).join('.'))
        .slice(type === 'DS' ? 1 : 0)
        .find((cut) =>
          records.some((record) => record.name === cut && record.type === 'NS'),
        ) ?? '.';
    return {
      answers: records.filter(
        (record) => record.name === name && record.type === type,
      ),
      coveringRrsigs: records.flatMap((record) =>
        record.name === name &&
        record.type === 'RRSIG' &&
        record.data.typeCovered === type
          ? [record.data]
          : [],
      ),
      rcode:
        name === '.' ||
        records.some(
          (record) => record.name === name || record.name.endsWith(`.${name}`),
        )
          ? 'NOERROR'
          : 'NXDOMAIN',
      zone,
    };
  };

// The real root DNSKEY RRset, both IANA KSKs included, and its RRSIG.
const root = (): Answer[] => [
  ...ROOT_DNSKEYS.map((key) => keyRecord('.', key)),
  { name: '.', type: 'RRSIG', ttl: 60, data: ROOT_DNSKEY_RRSIG },
];

const walk = (name: string, records: (Answer | Answer[])[]) =>
  resolveDsChain(name, dnsTree(records.flat()), NOW);

describe('resolveDsChain', () => {
  it('follows matching DS digests to the full queried name', async () => {
    const chain = await walk('WWW.Example.COM.', [
      root(),
      signedZone('com'),
      signedZone('example.com'),
      signedZone('www.example.com'),
    ]);
    expect(chain.verdict).toBe('intact');
    expect(chain.breakAt).toBeUndefined();
    expect(chain.name).toBe('www.example.com');
    expect(chain.zones.map((zone) => zone.name)).toEqual([
      '.',
      'com',
      'example.com',
      'www.example.com',
    ]);
    expect(chain.zones.every((zone) => zone.status === 'intact')).toBe(true);
    expect(chain.zones.map((zone) => zone.keySignature?.outcome)).toEqual([
      'valid',
      'valid',
      'valid',
      'valid',
    ]);
    expect(chain.zones[1].keySignature).toMatchObject({
      expiration: WINDOW.expiration,
    });
  });

  it('keeps a host inside its signed zone instead of calling it unsigned', async () => {
    const chain = await walk('www.example.com', [
      root(),
      signedZone('com'),
      signedZone('example.com'),
      host('www.example.com'),
    ]);
    expect(chain.verdict).toBe('intact');
    expect(chain.breakAt).toBeUndefined();
    expect(chain.name).toBe('www.example.com');
    expect(chain.zones.map((zone) => zone.name)).toEqual([
      '.',
      'com',
      'example.com',
    ]);
  });

  it('skips empty non-terminals between zone apexes', async () => {
    const chain = await walk('a.b.example.com', [
      root(),
      signedZone('com'),
      signedZone('example.com'),
      signedZone('a.b.example.com'),
    ]);
    expect(chain.verdict).toBe('intact');
    expect(chain.zones.map((zone) => zone.name)).toEqual([
      '.',
      'com',
      'example.com',
      'a.b.example.com',
    ]);
  });

  it('finds an unsigned child by its own SOA when it shares the parent servers', async () => {
    // No NS for example.com: the com servers host the child too, so the walk
    // is never referred and only the owned SOA marks the apex.
    const chain = await walk('www.example.com', [
      root(),
      signedZone('com'),
      soa('example.com'),
      host('www.example.com'),
    ]);
    expect(chain.verdict).toBe('unsigned');
    expect(chain.breakAt).toBe('example.com');
    expect(chain.zones.map((zone) => zone.name)).toEqual([
      '.',
      'com',
      'example.com',
    ]);
  });

  it('finds an unsigned delegation whose servers host no zone at the cut', async () => {
    // Like www.archives.gov: the parent delegates the name without a DS, but
    // the child servers answer from the parent's zone, so the child has no
    // SOA of its own and only the referral marks the cut.
    const chain = await walk('www.example.com', [
      root(),
      signedZone('com'),
      signedZone('example.com'),
      ns('www.example.com'),
      host('www.example.com'),
    ]);
    expect(chain.verdict).toBe('unsigned');
    expect(chain.breakAt).toBe('www.example.com');
    expect(chain.zones.map((zone) => zone.name)).toEqual([
      '.',
      'com',
      'example.com',
      'www.example.com',
    ]);
  });

  it('keeps a wildcard query name and covers it by its zone', async () => {
    const chain = await walk('*.example.com', [
      root(),
      signedZone('com'),
      signedZone('example.com'),
    ]);
    expect(chain.verdict).toBe('intact');
    expect(chain.name).toBe('*.example.com');
    expect(chain.zones.at(-1)?.name).toBe('example.com');
  });

  it('marks an unsigned TLD and its descendants unsigned', async () => {
    const chain = await walk('example.com', [com(), signedZone('example.com')]);
    expect(chain.verdict).toBe('unsigned');
    expect(chain.breakAt).toBe('com');
    expect(chain.zones.map((zone) => zone.status)).toEqual([
      'intact',
      'unsigned',
      'unsigned',
    ]);
    // Nothing above vouches for example.com's DS, so its keys are not checked.
    expect(chain.zones[2].keySignature).toBeUndefined();
  });

  it('reports a published DS with no matching DNSKEY as a mismatch', async () => {
    const chain = await walk('com', com(dsRecord('com', KSK.dnskey, 2, true)));
    expect(chain.verdict).toBe('mismatch');
    expect(chain.breakAt).toBe('com');
    expect(chain.zones[1].dsRecords[0].matched).toBe(false);
  });

  it('links both pinned IANA root KSKs and verifies the root key set', async () => {
    const chain = await walk('.', root());
    expect(chain.verdict).toBe('intact');
    expect(chain.zones[0].dsRecords.map((ds) => ds.matched)).toEqual([
      true,
      true,
    ]);
    expect(chain.zones[0].keySignature?.outcome).toBe('valid');
  });

  it('throws a retryable error when root DNSKEYs are empty', async () => {
    await expect(walk('example.com', [])).rejects.toMatchObject({
      payload: { retryable: true },
    });
  });

  it('treats NXDOMAIN at the queried name as not found', async () => {
    await expect(
      walk('missing.example.com', [
        root(),
        signedZone('com'),
        signedZone('example.com'),
      ]),
    ).rejects.toBeInstanceOf(DsChainNameNotFoundError);
  });

  it('rejects names over 16 labels before querying', async () => {
    let queried = false;
    await expect(
      resolveDsChain(
        Array.from({ length: 17 }, () => 'a').join('.'),
        async () => {
          queried = true;
          return { answers: [], zone: '.' };
        },
      ),
    ).rejects.toBeInstanceOf(UserFacingError);
    expect(queried).toBe(false);
  });

  it('prefers SHA-256 when SHA-1 and SHA-256 DS records coexist', async () => {
    const chain = await walk(
      'com',
      com(dsRecord('com'), dsRecord('com', KSK.dnskey, 1, true)),
    );
    expect(chain.verdict).toBe('intact');
    expect(chain.zones[1].dsRecords).toEqual([
      expect.objectContaining({
        digestType: 2,
        matched: true,
        weakDigest: false,
      }),
      expect.objectContaining({
        digestType: 1,
        matched: false,
        weakDigest: true,
      }),
    ]);

    const reverse = await walk(
      'com',
      com(dsRecord('com', KSK.dnskey, 1), dsRecord('com', KSK.dnskey, 2, true)),
    );
    expect(reverse.verdict).toBe('mismatch');
  });

  it('does not treat a DNSKEY owned by a host as a zone cut', async () => {
    const chain = await walk('www.example.com', [
      root(),
      signedZone('com'),
      signedZone('example.com'),
      keyRecord('www.example.com'),
    ]);
    expect(chain.verdict).toBe('intact');
    expect(chain.zones.at(-1)?.name).toBe('example.com');
  });

  it('breaks on an expired DNSKEY signature and propagates it down', async () => {
    const expired = { inception: NOW - 2 * DAY, expiration: NOW - DAY };
    const chain = await walk('www.example.com', [
      root(),
      signedZone('com'),
      ns('example.com'),
      soa('example.com'),
      keyRecord('example.com'),
      dsRecord('example.com'),
      keySig('example.com', [KSK.dnskey], KSK, expired),
      signedZone('www.example.com'),
    ]);
    expect(chain.verdict).toBe('bad-signature');
    expect(chain.breakAt).toBe('example.com');
    expect(chain.zones[2].keySignature).toEqual({
      outcome: 'expired',
      ...expired,
    });
    expect(chain.zones[3].status).toBe('bad-signature');
    expect(chain.zones[3].keySignature).toBeUndefined();
  });

  it('judges each signature when it is checked, not when the walk started', async () => {
    // Only Date is faked, so the walk's own awaits still run.
    vi.useFakeTimers({ toFake: ['Date'] });
    try {
      vi.setSystemTime(NOW * 1000);
      const tree = dnsTree([root(), signedZone('com')].flat());
      const chain = await resolveDsChain('com', async (name, type) => {
        // com's key-set signature expires while the walk is under way.
        if (name === 'com') vi.setSystemTime((WINDOW.expiration + 1) * 1000);
        return tree(name, type);
      });
      expect(chain.zones[0].keySignature?.outcome).toBe('valid');
      expect(chain.zones[1].keySignature?.outcome).toBe('expired');
    } finally {
      vi.useRealTimers();
    }
  });

  it('breaks when the DNSKEY RRSIG is missing', async () => {
    const chain = await walk('com', [
      root(),
      soa('com'),
      keyRecord('com'),
      dsRecord('com'),
    ]);
    expect(chain.verdict).toBe('bad-signature');
    expect(chain.zones[1].keySignature).toEqual({ outcome: 'missing' });
  });

  it('breaks when only a key no DS links signed the key set', async () => {
    const zsk = genKey(13);
    const keys = [KSK.dnskey, zsk.dnskey];
    const chain = await walk(
      'com',
      [
        root(),
        soa('com'),
        keys.map((key) => keyRecord('com', key)),
        dsRecord('com'),
        keySig('com', keys, zsk),
      ].flat(),
    );
    expect(chain.verdict).toBe('bad-signature');
    expect(chain.zones[1].keySignature?.outcome).toBe('unauthenticated-signer');
  });

  it('breaks when the served key set is not the one that was signed', async () => {
    const extra = genKey(13).dnskey;
    const chain = await walk('com', [
      com(dsRecord('com')),
      keyRecord('com', extra),
    ]);
    expect(chain.verdict).toBe('bad-signature');
    expect(chain.zones[1].keySignature?.outcome).toBe('invalid');
  });

  it('names the queries still in flight when the deadline passes', async () => {
    vi.useFakeTimers();

    try {
      const settled = resolveDsChainWithin(
        'com',
        () => new Promise(() => {}),
        1000,
      ).catch((error: unknown) => error);
      await vi.advanceTimersByTimeAsync(1000);
      const error = await settled;

      expect(error).toBeInstanceOf(UserFacingError);
      expect((error as Error).cause).toMatchObject({
        message: 'Still waiting after 1000ms for: . DNSKEY',
      });
    } finally {
      vi.useRealTimers();
    }
  });
});