Class Net::DNS::Header
In: lib/net/dns/header.rb
Parent: Object

Name

Net::DNS::Header - DNS packet header class

Synopsis

  require 'net/dns/header'

Description

The Net::DNS::Header class represents the header portion of a DNS packet. An Header object is created whenever a new packet is parsed or as user request.

  header = Net::DNS::Header.new
    # ;; id = 18123
    # ;; qr = 0       opCode: 0       aa = 0  tc = 0  rd = 1
    # ;; ra = 0       ad = 0  cd = 0  rcode = 0
    # ;; qdCount = 1  anCount = 0     nsCount = 0     arCount = 0

  header.format
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |             18123             |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |0|   0   |0|0|1|0|0| 0 |   0   |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               1               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               0               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               0               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               0               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  # packet is an instance of Net::DNS::Packet
  header = packet.header
  puts "Answer is #{header.auth? ? '' : 'non'} authoritative"

A lot of methods were written to keep a compatibility layer with the Perl version of the library, as long as methods name which are more or less the same.

Methods

aa=   ad=   anCount=   arCount=   auth?   cd=   checking?   data   error?   format   id=   inspect   new   nsCount=   opCode=   opCode_str   parse   qdCount=   qr=   query?   rCode=   rCode_str   r_available?   ra=   rd=   recursive=   recursive?   response?   tc=   truncated?   verified?  

Classes and Modules

Class Net::DNS::Header::DuplicateIDError
Class Net::DNS::Header::Error
Class Net::DNS::Header::RCode
Class Net::DNS::Header::WrongCountError
Class Net::DNS::Header::WrongOpcodeError
Class Net::DNS::Header::WrongRecursiveError

Constants

QUERY = 0   Constant for opCode query
IQUERY = 1   Constant for opCode iquery
STATUS = 2   Constant for opCode status
OPARR = %w[QUERY IQUERY STATUS]   Array with given strings

Attributes

anCount  [R]  Reader for answer section entries number
arCount  [R]  Reader for addictional section entries number
id  [R]  Reader for id attribute
nsCount  [R]  Reader for authority section entries number
opCode  [R]  Reader for the operational code
qdCount  [R]  Reader for question section entries number
rCode  [R]  Reader for the rCode instance

Public Class methods

Creates a new Net::DNS::Header object with the desired values, which can be specified as an Hash argument. When called without arguments, defaults are used. If a data string is passed, values are taken from parsing the string.

Examples:

  # Create a new Net::DNS::Header object
  header = Net::DNS::Header.new

  # Create a new Net::DNS::Header object passing values
  header = Net::DNS::Header.new(:opCode => 1, :rd => 0)

  # Create a new Net::DNS::Header object with binary data
  header = Net::DNS::Header.new(data)

Default values are:

  :id => auto generated
  :qr      => 0 # Query response flag
  :aa      => 0 # Authoritative answer flag
  :tc      => 0 # Truncated packet flag
  :ra      => 0 # Recursiond available flag
  :rCode   => 0 # Response code (status of the query)
  :opCode  => 0 # Operational code (purpose of the query)
  :cd      => 0 # Checking disable flag
  :ad      => 0 # Only relevant in DNSSEC context
  :rd      => 1 # Recursion desired flag
  :qdCount => 1 # Number of questions in the dns packet
  :anCount => 0 # Number of answer RRs in the dns packet
  :nsCount => 0 # Number of authoritative RRs in the dns packet
  :arCount => 0 # Number of additional RRs in the dns packet

See also each option for a detailed explanation of usage.

Creates a new Net::DNS::Header object from binary data, which is passed as a string object as argument. The configurations parameters are taken from parsing the string.

Example:

  # Create a new Net::DNS::Header object with binary data
  header = Net::DNS::Header.new(data)

  header.auth?
    #=> "true" if it comes from authoritative name server

Public Instance methods

Set the aa flag (authoritative answer) to either true or false. You can also use 0 or 1.

This flag indicates whether a DNS answer packet contains authoritative data, meaning that is was generated by a nameserver authoritative for the domain of the question.

Must only be set to true in DNS answer packets.

Set the ad flag to either true ot false. You can also use 0 or 1.

The AD bit is only set on answers where signatures have been cryptographically verified or the server is authoritative for the data and is allowed to set the bit by policy.

Sets the number of RRs in an answer section

Sets the number of RRs in an addictional section

Checks whether the response is authoritative

  if header.auth?
    puts "Response is authoritative"
  else
    puts "Answer is NOT authoritative"
  end

Set the cd flag (checking disabled) to either true ot false. You can also use 0 or 1.

Checks whether checking is enabled or disabled.

Checking is enabled by default.

Returns the header data in binary format, appropriate for use in a DNS query packet.

  hdata = header.data
  puts "Header is #{hdata.size} bytes"

Checks for errors in the DNS packet

  unless header.error?
    puts "No errors in DNS answer packet"
  end

The Net::DNS::Header#format method prints out the header in a special ascii representation of data, in a way similar to those often found on RFCs.

  p Net::DNS::Header.new.format
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |             18123             |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |0|   0   |0|0|1|0|0| 0 |   0   |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               1               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               0               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               0               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    #  |               0               |
    #  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

This can be very usefull for didactical purpouses :)

Set the ID for the current header. Useful when performing security tests.

Inspect method, prints out all the options and relative values.

  p Net::DNS::Header.new
    # ;; id = 18123
    # ;; qr = 0       opCode: 0       aa = 0  tc = 0  rd = 1
    # ;; ra = 0       ad = 0  cd = 0  rcode = 0
    # ;; qdCount = 1  anCount = 0     nsCount = 0     arCount = 0

This method will maybe be changed in the future to a more pretty way of display output.

Sets the number of RRs in an authority section

Set the opCode variable to a new value. This fields indicates the type of the question present in the DNS packet; val can be one of the values QUERY, IQUERY or STATUS.

  • QUERY is the standard DNS query
  • IQUERY is the inverse query
  • STATUS is used to query the nameserver for its status

Example:

  include Net::DNS
  header = Header.new
  header.opCode = Header::STATUS

Returns a string representation of the opCode

  puts "Packet is a #{header.opCode_str}"
    #=> Packet is a QUERY

Sets the number of entries in a question section

Set the qr query response flag to be either true or false. You can also use the values 0 and 1. This flag indicates if the DNS packet contains a query or an answer, so it should be set to true in DNS answer packets. If qr is true, the packet is a response.

Checks whether the header is a query (qr bit set to 0)

Set the rCode value. This should only be done in DNS answer packets.

Returns an error array for the header response code, or nil if no error is generated.

  error, cause = header.rCode_str
  puts "Error #{error} cause by: #{cause}" if error
    #=> Error ForErr caused by: The name server
    #=> was unable to interpret the query

Checks whether recursion is available. This flag is usually set by nameservers to indicate that they support recursive-type queries.

Set the ra flag (recursion available) to either true or false. You can also use 0 and 1.

This flag must only be set in DNS answer packets.

Alias for Header#recursive= to keep compatibility with the Perl version.

Sets the recursion desidered bit. Remember that recursion query support is optional.

  header.recursive = true
  hdata = header.data # suitable for sending

Consult RFC1034 and RFC1035 for a detailed explanation of how recursion works.

Checks whether the packet has a recursion bit set, meaning that recursion is desired

Checks whether the header is a response (qr bit set to 1)

Set the tc flag (truncated packet) to either true ot false. You can also use 0 or 1.

The truncated flag is used in response packets to indicate that the amount of data to be trasmitted exceedes the maximum allowed by the protocol in use, tipically UDP, and that the data present in the packet has been truncated. A different protocol (such has TCP) need to be used to retrieve full data.

Must only be set in DNS answer packets.

Checks whether the packet was truncated

  # Sending packet using UDP
  if header.truncated?
    puts "Warning, packet has been truncated!"
    # Sending packet using TCP
  end
  # Do something with the answer

Checks whether ad flag has been set.

This flag is only relevant in DNSSEC context.

[Validate]