tessl/npm-dns-packet

An abstract-encoding compliant module for encoding and decoding DNS packets with support for all major DNS record types and transport protocols

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Packet Operations

Name: tessl/npm-dns-packet
Author: tessl

Core packet encoding and decoding functionality for DNS messages with support for both UDP and TCP transport protocols.

Capabilities

Encode

Encodes a DNS packet into a buffer containing a UDP payload.

/**
 * Encodes a DNS packet into a buffer containing a UDP payload
 * @param {Object} packet - DNS packet object to encode
 * @param {Buffer} [buf] - Optional pre-allocated buffer 
 * @param {number} [offset=0] - Optional offset within buffer
 * @returns {Buffer} Encoded DNS packet buffer
 */
function encode(packet, buf, offset);

The packet parameter should be a DNS packet object with the following structure:

interface DNSPacket {
  type: 'query' | 'response';
  id?: number;
  flags?: number;
  questions?: Question[];
  answers?: Answer[];
  authorities?: Answer[];
  additionals?: Answer[];
}

interface Question {
  type: string; // DNS record type like 'A', 'AAAA', 'MX', etc.
  class?: string; // DNS class, defaults to 'IN'
  name: string; // Domain name to query
}

interface Answer {
  type: string; // DNS record type
  class?: string; // DNS class, defaults to 'IN'
  name: string; // Domain name
  ttl?: number; // Time to live in seconds
  // Additional record-specific properties based on type
}

Usage Example:

const dnsPacket = require('dns-packet');

const packet = {
  type: 'query',
  id: 1,
  flags: dnsPacket.RECURSION_DESIRED,
  questions: [{
    type: 'A',
    name: 'example.com'
  }]
};

const buf = dnsPacket.encode(packet);
console.log('Encoded packet size:', buf.length);

Decode

Decodes a DNS packet from a buffer containing a UDP payload.

/**
 * Decodes a DNS packet from a buffer containing a UDP payload
 * @param {Buffer} buf - Buffer containing DNS packet data
 * @param {number} [offset=0] - Optional offset within buffer
 * @returns {Object} Decoded DNS packet object
 */
function decode(buf, offset);

Usage Example:

const dnsPacket = require('dns-packet');

// Assuming 'responseBuffer' contains a DNS response
const packet = dnsPacket.decode(responseBuffer);

console.log('Packet type:', packet.type);
console.log('Questions:', packet.questions);
console.log('Answers:', packet.answers);

Stream Encode

Encodes a DNS packet into a buffer containing a TCP payload with proper length prefixing.

/**
 * Encodes a DNS packet into a buffer containing a TCP payload
 * @param {Object} packet - DNS packet object to encode
 * @returns {Buffer} Encoded TCP DNS packet with length prefix
 */
function streamEncode(packet);

Usage Example:

const dnsPacket = require('dns-packet');

const packet = {
  type: 'query',
  id: 1,
  questions: [{ type: 'A', name: 'example.com' }]
};

const tcpBuffer = dnsPacket.streamEncode(packet);
// Buffer includes 2-byte length prefix for TCP transport

Stream Decode

Decodes a DNS packet from a buffer containing a TCP payload with length prefix.

/**
 * Decodes a DNS packet from a buffer containing a TCP payload
 * @param {Buffer} buf - Buffer containing length-prefixed DNS data
 * @returns {Object|null} Decoded DNS packet object, or null if insufficient data
 */
function streamDecode(buf);

Usage Example:

const dnsPacket = require('dns-packet');

// Assuming 'tcpBuffer' contains TCP DNS data with length prefix
const packet = dnsPacket.streamDecode(tcpBuffer);
if (packet) {
  console.log('Decoded TCP packet:', packet);
} else {
  console.log('Insufficient data for complete packet');
}

Encoding Length

Returns the number of bytes needed to encode a DNS packet.

/**
 * Returns how many bytes are needed to encode the DNS packet
 * @param {Object} packet - DNS packet object
 * @returns {number} Number of bytes required for encoding
 */
function encodingLength(packet);

Usage Example:

const dnsPacket = require('dns-packet');

const packet = {
  type: 'query',
  questions: [{ type: 'A', name: 'example.com' }]
};

const length = dnsPacket.encodingLength(packet);
console.log('Packet will require', length, 'bytes');

// Pre-allocate buffer of exact size
const buf = Buffer.alloc(length);
dnsPacket.encode(packet, buf);

Bytes Tracking

All encoding and decoding functions set a .bytes property indicating the number of bytes consumed or produced:

// Regular UDP encoding/decoding
const buf = dnsPacket.encode(packet); 
console.log('Bytes written:', dnsPacket.encode.bytes);

const decoded = dnsPacket.decode(buffer);
console.log('Bytes read:', dnsPacket.decode.bytes);

// TCP stream encoding/decoding
const tcpBuf = dnsPacket.streamEncode(packet);
console.log('TCP bytes written:', dnsPacket.streamEncode.bytes);

const tcpDecoded = dnsPacket.streamDecode(tcpBuffer);
if (tcpDecoded) {
  console.log('TCP bytes read:', dnsPacket.streamDecode.bytes);
}

Install with Tessl CLI