search

relaycorp / dnssec-js

Resolver-agnostic DNSSEC library for Node.js
https://www.npmjs.com/package/@relaycorp/dnssec
MIT License
12 stars 3 forks source link
dnssec

readme

@relaycorp/dnssec

npm version

This is a resolver-agnostic DNSSEC verification library for Node.js that allows you to use any transport you want: UDP, DNS-over-TLS (DoT), DNS-over-HTTPS (DoH), etc.

The latest version can be installed from NPM:

npm install @relaycorp/dnssec

Usage

You need to write a thin integration with your preferred resolver, keeping the following in mind:

For example, this is how you could use dohdec's DNS-over-HTTPS resolver with Cloudflare to retrieve A records for a particular domain name:

// main.js
import { dnssecLookUp, Question, SecurityStatus } from '@relaycorp/dnssec';
import { DNSoverHTTPS } from 'dohdec';

const doh = new DNSoverHTTPS({ url: 'https://cloudflare-dns.com/dns-query' });

async function getARecord(domain) {
  return await dnssecLookUp(new Question(domain, 'A'), async (question) =>
    doh.lookup(question.name, {
      rrtype: question.getTypeName(),
      json: false, // Request DNS message in wire format
      decode: false, // Don't parse the DNS message
      dnssec: true, // Retrieve RRSIG records
      dnssecCheckingDisabled: true, // Disable server-side DNSSEC validation
    }),
  );
}

const [domainName] = process.argv.slice(2);
const result = await getARecord(domainName);
if (result.status === SecurityStatus.SECURE) {
  console.log(`${domainName}/A =`, result.result);
} else {
  const reason = result.reasonChain.join(', ');
  console.error(`DNSSEC verification for ${domain}/A failed: ${reason}`);
}

And here's what requesting a valid A record would look like with the script above:

$ node main.js example.com
example.com/A = RrSet {
  name: 'example.com.',
  classId: 1,
  type: 1,
  ttl: 83076,
  records: [
    DnsRecord {
      ttl: 83076,
      name: 'example.com.',
      typeId: 1,
      classId: 1,
      dataSerialised: <Buffer 5d b8 d8 22>,
      dataFields: '93.184.216.34'
    }
  ]
}

Successful RRset

When DNSSEC validation succeeds, you get a VerifiedRrSet object with the following properties:

Error handling

As this is primarily a DNSSEC library, we treat DNS and DNSSEC errors differently:

However, errors are thrown upon attempting to parse malformed RDATA values for DNSSEC records -- we use a third-party library that parses the DNS message eagerly.

Validation period

By default, DNSSEC signatures MUST be valid at the time the dnssecLookUp() function is called, but this can be customised by passing a Date or IDatePeriod object.

An IDatePeriod object is useful when you just want signatures to be valid at any point within a given time period. For example, if you want to tolerate clock drift, you could accept signatures valid in the past hour:

import { IDatePeriod, dnssecLookUp } from '@relaycorp/dnssec';
import { subHours } from 'date-fns';

const now = new Date();
const datePeriod: IDatePeriod = { start: subHours(now, 1), end: now };
dnssecLookUp(QUESTION, RESOLVER, { dateOrPeriod: datePeriod });

Custom trust anchors

By default, the root DNSKEY(s) are verified against a local copy of IANA's trust anchors. This can be customised with the trustAnchors option; e.g.:

import {
  dnssecLookUp,
  DnssecAlgorithm,
  DigestType,
  TrustAnchor,
} from '@relaycorp/dnssec';

const customTrustAnchor: TrustAnchor = {
  algorithm: DnssecAlgorithm.RSASHA256,
  digest: Buffer.from('the digest'),
  digestType: DigestType.SHA256,
  keyTag: 42,
};
dnssecLookUp(QUESTION, RESOLVER, { trustAnchors: [customTrustAnchor] });

Responses parsed eagerly

If your DNS lookup library parses responses eagerly and doesn't give you access to the original response in wire format, you will have to convert their messages to Message instances. Refer to our API docs to learn how to initialise Messages.

Testing

To facilitate the simulation of the various outcomes of DNSSEC validation, we provide the MockChain utility so that you can pass a custom resolver and trust anchor to dnssecLookUp(). This is particularly useful in unit tests where you aren't able to mock this module (e.g., Jest doesn't support mocking our ESM as of this writing).

The following example shows how to generate a verified RRset:

import {
  dnssecLookUp,
  DnsRecord,
  MockChain,
  RrSet,
  SecurityStatus,
} from '@relaycorp/dnssec';

const RECORD = new DnsRecord(
  `example.com.`,
  'TXT',
  DnsClass.IN,
  42,
  'The data',
);
const QUESTION = RECORD.makeQuestion();
const RRSET = RrSet.init(QUESTION, [RECORD]);

test('Generating a SECURE result', async () => {
  const mockChain = await MockChain.generate(RECORD.name);

  const { resolver, trustAnchors } = mockChain.generateFixture(
    RRSET,
    SecurityStatus.SECURE,
  );

  const result = await dnssecLookUp(QUESTION, resolver, { trustAnchors });
  expect(result).toStrictEqual({
    status: SecurityStatus.SECURE,
    result: RRSET,
  });
});

API documentation

The API documentation is available on docs.relaycorp.tech.

Missing functionality

This library implements all the relevant RFCs defining DNSSEC, except for the following functionality that we didn't need, but for which you're welcome to propose PRs:

The following DNSSEC algorithms are unsupported, and we probably won't accept PRs for them:

Alternatives considered

As surprising as it may sound, there's no (reliable) way to do DNSSEC verification in Node.js in 2022, so when you see a JS app or library that claims DNSSEC support, chances are they're just blindly trusting a resolver like Cloudflare or Google -- which, admittedly, is sufficient in many cases and even desirable for performance reasons.

The Node.js team considered adding DNSSEC support but ruled it out due to lack of support in their upstream DNS library. As a consequence, two libraries have tried to fill the vacuum:

Contributions

We love contributions! If you haven't contributed to a Relaycorp project before, please take a minute to read our guidelines first.