Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mafintosh/dns-packet

An abstract-encoding compliant module for encoding / decoding DNS packets
https://github.com/mafintosh/dns-packet

Last synced: 29 days ago
JSON representation

An abstract-encoding compliant module for encoding / decoding DNS packets

Lists

README 

        
# dns-packet

[![](https://img.shields.io/npm/v/dns-packet.svg?style=flat)](https://www.npmjs.org/package/dns-packet) [![](https://img.shields.io/npm/dm/dns-packet.svg)](https://www.npmjs.org/package/dns-packet) [![](https://github.com/github/mafintosh/dns-packet/workflows/ci.yml/badge.svg)](https://github.com/github/mafintosh/dns-packet/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/mafintosh/dns-packet/badge.svg?branch=master)](https://coveralls.io/github/mafintosh/dns-packet?branch=master)



An [abstract-encoding](https://github.com/mafintosh/abstract-encoding) compliant module for encoding / decoding DNS packets. Lifted out of [multicast-dns](https://github.com/mafintosh/multicast-dns) as a separate module.



```

npm install dns-packet

```



## UDP Usage



``` js

const dnsPacket = require('dns-packet')

const dgram = require('dgram')



const socket = dgram.createSocket('udp4')



const buf = dnsPacket.encode({

  type: 'query',

  id: 1,

  flags: dnsPacket.RECURSION_DESIRED,

  questions: [{

    type: 'A',

    name: 'google.com'

  }]

})



socket.on('message', message => {

  console.log(dnsPacket.decode(message)) // prints out a response from google dns

})



socket.send(buf, 0, buf.length, 53, '8.8.8.8')

```



Also see [the UDP example](examples/udp.js).



## TCP, TLS, HTTPS



While DNS has traditionally been used over a datagram transport, it is increasingly being carried over TCP for larger responses commonly including DNSSEC responses and TLS or HTTPS for enhanced security. See below examples on how to use `dns-packet` to wrap DNS packets in these protocols:



- [TCP](examples/tcp.js)

- [DNS over TLS](examples/tls.js)

- [DNS over HTTPS](examples/doh.js)



## API



#### `var buf = packets.encode(packet, [buf], [offset])`



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



#### `var packet = packets.decode(buf, [offset])`



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



#### `var buf = packets.streamEncode(packet, [buf], [offset])`



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



#### `var packet = packets.streamDecode(buf, [offset])`



Decode a DNS packet from a buffer containing a TCP payload.



#### `var len = packets.encodingLength(packet)`



Returns how many bytes are needed to encode the DNS packet



## Packets



Packets look like this



``` js

{

  type: 'query|response',

  id: optionalIdNumber,

  flags: optionalBitFlags,

  questions: [...],

  answers: [...],

  additionals: [...],

  authorities: [...]

}

```



The bit flags available are



``` js

packet.RECURSION_DESIRED

packet.RECURSION_AVAILABLE

packet.TRUNCATED_RESPONSE

packet.AUTHORITATIVE_ANSWER

packet.AUTHENTIC_DATA

packet.CHECKING_DISABLED

```



To use more than one flag bitwise-or them together



``` js

var flags = packet.RECURSION_DESIRED | packet.RECURSION_AVAILABLE

```



And to check for a flag use bitwise-and



``` js

var isRecursive = message.flags & packet.RECURSION_DESIRED

```



A question looks like this



``` js

{

  type: 'A', // or SRV, AAAA, etc

  class: 'IN', // one of IN, CS, CH, HS, ANY. Default: IN

  name: 'google.com' // which record are you looking for

}

```



And an answer, additional, or authority looks like this



``` js

{

  type: 'A', // or SRV, AAAA, etc

  class: 'IN', // one of IN, CS, CH, HS

  name: 'google.com', // which name is this record for

  ttl: optionalTimeToLiveInSeconds,

  (record specific data, see below)

}

```



## Supported record types



#### `A`



``` js

{

  data: 'IPv4 address' // fx 127.0.0.1

}

```



#### `AAAA`



``` js

{

  data: 'IPv6 address' // fx fe80::1

}

```



#### `CAA`



``` js

{

  flags: 128, // octet

  tag: 'issue|issuewild|iodef',

  value: 'ca.example.net',

  issuerCritical: false

}

```



#### `CNAME`



``` js

{

  data: 'cname.to.another.record'

}

```



#### `DNAME`



``` js

{

  data: 'dname.to.another.record'

}

```



#### `DNSKEY`



``` js

{

  flags: 257, // 16 bits

  algorithm: 1, // octet

  key: Buffer

}

```



#### `DS`



``` js

{

  keyTag: 12345,

  algorithm: 8,

  digestType: 1,

  digest: Buffer

}

```



#### `HINFO`



``` js

{

  data: {

    cpu: 'cpu info',

    os: 'os info'

  }

}

```



#### `MX`



``` js

{

  preference: 10,

  exchange: 'mail.example.net'

}

```



#### `NAPTR`



``` js

{

  data:

    {

      order: 100,

      preference: 10,

      flags: 's',

      services: 'SIP+D2U',

      regexp: '!^.*$!sip:[email protected]!',

      replacement: '_sip._udp.example.com'

    }

}

```



#### `NS`



``` js

{

  data: nameServer

}

```



#### `NSEC`



``` js

{

  nextDomain: 'a.domain',

  rrtypes: ['A', 'TXT', 'RRSIG']

}

```



#### `NSEC3`



``` js

{

  algorithm: 1,

  flags: 0,

  iterations: 2,

  salt: Buffer,

  nextDomain: Buffer, // Hashed per RFC5155

  rrtypes: ['A', 'TXT', 'RRSIG']

}

```



#### `NULL`



``` js

{

  data: Buffer('any binary data')

}

```



#### `OPT`



[EDNS0](https://tools.ietf.org/html/rfc6891) options.



``` js

{

  type: 'OPT',

  name: '.',

  udpPayloadSize: 4096,

  flags: packet.DNSSEC_OK,

  options: [{

    // pass in any code/data for generic EDNS0 options

    code: 12,

    data: Buffer.alloc(31)

  }, {

    // Several EDNS0 options have enhanced support

    code: 'PADDING',

    length: 31,

  }, {

    code: 'CLIENT_SUBNET',

    family: 2, // 1 for IPv4, 2 for IPv6

    sourcePrefixLength: 64, // used to truncate IP address

    scopePrefixLength: 0,

    ip: 'fe80::',

  }, {

    code: 'TCP_KEEPALIVE',

    timeout: 150 // increments of 100ms.  This means 15s.

  }, {

    code: 'KEY_TAG',

    tags: [1, 2, 3],

  }]

}

```



The options `PADDING`, `CLIENT_SUBNET`, `TCP_KEEPALIVE` and `KEY_TAG` support enhanced de/encoding. See [optionscodes.js](https://github.com/mafintosh/dns-packet/blob/master/optioncodes.js) for all supported option codes. If the `data` property is present on a option, it takes precedence. On decoding, `data` will always be defined.



#### `PTR`



``` js

{

  data: 'points.to.another.record'

}

```



#### `RP`



``` js

{

  mbox: 'admin.example.com',

  txt: 'txt.example.com'

}

```



#### `SSHFP`



``` js

{

  algorithm: 1,

  hash: 1,

  fingerprint: 'A108C9F834354D5B37AF988141C9294822F5BC00'

}

````



#### `RRSIG`



``` js

{

  typeCovered: 'A',

  algorithm: 8,

  labels: 1,

  originalTTL: 3600,

  expiration: timestamp,

  inception: timestamp,

  keyTag: 12345,

  signersName: 'a.name',

  signature: Buffer

}

```



#### `SOA`



``` js

{

  data:

    {

      mname: domainName,

      rname: mailbox,

      serial: zoneSerial,

      refresh: refreshInterval,

      retry: retryInterval,

      expire: expireInterval,

      minimum: minimumTTL

    }

}

```



#### `SRV`



``` js

{

  data: {

    port: servicePort,

    target: serviceHostName,

    priority: optionalServicePriority,

    weight: optionalServiceWeight

  }

}

```



#### `TLSA`



``` js

{

  usage: 3,

  selector: 1,

  matchingType: 1,

  certificate: Buffer

}

```



#### `TXT`



``` js

{

  data: 'text' || Buffer || [ Buffer || 'text' ]

}

```



When encoding, scalar values are converted to an array and strings are converted to UTF-8 encoded Buffers. When decoding, the return value will always be an array of Buffer.



If you need another record type, open an issue and we'll try to add it.



## License



MIT