dnsserver.repy

"""
<Program Name>
  dnsserver.repy

<Date Created>
  August 12, 2010

<Author(s)>
  Sebastian Morgan
  sebass63@gmail.com

<Major Edits>
  None

<Purpose>
  Abstracts away the details of the DNS protocol, allowing the user to 
  implement a DNS receive-respond server with relative ease.

<Notes>
  While there is no use of locks in this code, it seems to be quite safe from 
  threading issues as of internal version 3.2, when multiple callback assignments 
  were made impossible.
"""




# These will contain important information about our callback function
# once it has been assigned. Note that callback_assigned is left public 
# as a flag for whether or not a callback has been assigned yet.
_dnsserver_callback_data = { 'callback_function': None,
                            'local_port': 0,
                            'local_ip': '' }




callback_assigned = False

refuse_ips = []


include dnscommon.repy




def dnsserver_registercallback(listen_port, listen_ip, callback_function):
  """
  <Purpose>
    This method populates the _dnsserver_callback_data dictionary, allowing 
    the client to register a callback function for handling DNS queries. This 
    method also begins listening on the specified port and network adapter 
    once it has finished callback registration.

  <Arguments>
    listen_port
      The UDP port on which we listen for DNS messages.

    listen_ip
      The IP address on which we listen for DNS messages. This will generally 
      be that returned by getmyip(), but we leave it up to the client to set 
      this, since there may be multiple network interfaces to choose from.

    callback_function
      The function which will be called whenever we receive a DNS message on 
      its associated port. This function should take exactly one argument: A 
      dictionary with the following form:

  {
    'raw_data':                <long string> (network raw)
    'remote_ip':               string (formatted unicode, IP Address)
    'remote_port':             integer
    'communication_id'         string (network raw)
    'query_response'           boolean
    'operation_code'           integer
    'authority_advisory'       boolean
    'truncation'               boolean
    'recursion_desired'        boolean
    'recursion_accepted'       boolean
    'z'                        boolean
    'authentic_data'           boolean
    'checking_disabled'        boolean
    'error_code'               integer (4 bit)
    'question_count'           integer (16 bit)
    'answer_count'             integer (16 bit)
    'authority_record_count'   integer (16 bit)
    'additional_record_count'  integer (16 bit)   )
    'questions': array of dictionaries containing:
        'name'                  string (formatted unicode, IP Address)
        'type'                  string (formatted unicode, eg A, AAAA, MX)
        'class'                 string (formatted unicode, eg IN, HE, CH)
    'answers': array of dictionaries containing:
        'name'                  string (formatted unicode, IP Address)
        'type'                  string (formatted unicode, eg A, AAAA, MX)
        'class'                 string (formatted unicode, eg IN, HE, CH)
        'time_to_live'          integer (seconds, 32 bit)
        'answer_data'           dictionary (format based on type)
  }

  # The 'answer_data' dictionary field can have various formats. Here are the 
  # three which are currently supported:
    SOA:
  'mname' <IP>
  'rname' <IP>
  'serial' <32 bit int>
  'refresh' <32 bit int>
  'retry' <32 bit int>
  'expire' <32 bit int>
  'minimum' <32 bit int>
    NS:
  'address' <Domain Name>
    A:
  'address' <IP>


  <Exceptions>
    Exception
      This is a global exception, but the only time it has been known to occur 
      is when recvmess is given a port which we aren't allowed to access.

  <Side Effects>
    When the callback function is registered, a listener will be opened on 
    listen_port, which could possibly interfere with other applications 
    running on the local machine. It's unlikely, but worth mentioning.

  <Returns>
    A connection handle, which can be used by stopcomm() to end the connection.
  """
  # Associate the connection handle with the callback function, so that we can 
  # retrieve it later.
  _dnsserver_callback_data['callback_function'] = callback_function
  _dnsserver_callback_data['local_port'] = listen_port
  _dnsserver_callback_data['local_ip'] = listen_ip
  callback_assigned = True

  # Start listening on the given listen_port. _connection_received_callback will
  # run whenever we receive a UDP packet on listen_port.
  connhandle = recvmess(listen_ip, listen_port, _connection_received_callback)

  # For now, we return the 
  # commhandle given by recvmess, so that the client can halt the connection 
  # as necessary. I'd like to abstract this, but it's not urgent, and I'm 
  # not sure of a good way to do it. There *is* the possibility of an error, if 
  # a connection is terminated, and then a new callback is registered on the 
  # same port, since we currently make no attempt to remove old callbacks from 
  # the dictionary.
  return connhandle




def _connection_received_callback(client_ip, client_port, dns_query_data, 
                                  connhandle):
  """
  <Purpose>
    This function is invoked whenever an existing listener receives a UDP 
    message. It is merely intended as a wrapper method to make the program 
    flow more clear and understandable, as well as simplifying testing.
  
  <Arguments>
    client_ip
      The IP address of the client who sent us the message. This is a string.

    client_port
      The port which the client has used (on their end) to send us the message.
      This is an integer.

    dns_query_data
      The content of the message, not including UDP protocol overhead, which we 
      have received. This is in string form.

    connhandle
      A handle for the connection. This can be used as an argument for 
      stopcomm() to end the connection.

  <Exceptions>
    KeyError
      In the normal course of events this won't happen, but if another method 
      or entity removes data from _dnsserver_callback_registry, it's possible 
      that we will get this when accessing local_port and local_ip.

  <Side Effects>
    None

  <Returns>
    None
  """
  # If the IP is blacklisted, we ignore the query.
  if client_ip in refuse_ips:
    return

  # Blacklist the connector's IP so that frivolous retries don't waste 
  # processing time.
  refuse_ips.append(client_ip)

  # Call this method to handle the processing of the request.
  response_string = _process_query(client_ip, client_port, dns_query_data, 
                                   connhandle)

  # Saves us space in the final function call of this method.
  local_ip = _dnsserver_callback_data['local_ip']
  local_port = _dnsserver_callback_data['local_port']


  # Finally, regardless of whether we're sending an error or a proper response,
  # we send what we have to the user. This method might need the GENIPORT 
  # explicitly passed at the end. I'd like for this not to be necessary, but 
  # we can make it work if it is.
  if response_string != None:
    sendmess(client_ip , client_port, response_string, local_ip, local_port)

  # Un-blacklist the client's IP.
  refuse_ips.remove(client_ip)




def _process_query(client_ip, client_port, dns_query_data, connhandle):
  """
  <Purpose>
    This method isolates the functionality of the DNS query callback 
    functionality, allowing us to test dnsserver functionality with 
    offline unit tests.

  <Arguments>
    client_ip
      The IP address of the client who sent us the message. This is a string.

    client_port
      The port which the client has used (on their end) to send us the message.
      This is an integer.

    dns_query_data
      The content of the message, not including UDP protocol overhead, which we 
      have received. This is in string form.

    connhandle
      A handle for the connection. This can be used as an argument for 
      stopcomm() to end the connection.

  <Exceptions>
    None specific. However, if the callback function registered by the user 
    (referred to in this method as 'cbfunc') throws an exception which we 
    don't understand, it will be raised here as well.

  <Side Effects>
    None

  <Returns>
    A packet response for the user, in string form.
  """
  # Check the packet for macroscopic problems, and record whether or not 
  # any were found.
  succeeded = True
  
  # Since making the parser intelligent would take up a lot of space and be 
  # a real headache to read, this method preparses the packet and flags us 
  # if something goes wrong during parsing. Succeeded will be set to false 
  # if we were unable to successfully parse.
  succeeded = _check_malformed_packet(dns_query_data)

  # We initialize the response we're going to send here, since there are two 
  # possible places where we'll be writing it.
  response_string = ""

  cbfunc = _dnsserver_callback_data['callback_function']

  if not succeeded:
    # If a problem was found with the packet, we respond with a generic 
    # error packet. This method will try to be helpful in the response, 
    # but there isn't a lot we can do.
    response_string = _write_error_packet(dns_query_data, 1)

  else:
    # Construct a dictionary from the raw packet data.
    packet_dict = convert_packet_to_dictionary(dns_query_data)

    # Debug logs need to have this information.
    packet_dict['remote_ip'] = client_ip
    packet_dict['remote_port'] = client_port

    # Initialize this outside of the try block, so that we have it later.
    response_dict = {}
    cbfunc_success = False

    # If an exception that we understand is thrown, we use it as a flag to 
    # return a specific error packet.
    try:
      # Pass the callback function the packet dictionary, and receive a 
      # response in dictionary form.
      response_dict = cbfunc(packet_dict)

      # Flag our progress, so that we know we executed successfully.
      cbfunc_success = True
    except MalformedPacketError:
      response_string = _write_error_packet(dns_query_data, _FORMAT_ERROR_CODE)
    except ServerFailedError:
      response_string = _write_error_packet(dns_query_data, _SERVER_FAIL_CODE)
    except NonexistentDomainError:
      response_string = _write_error_packet(dns_query_data, _NAME_ERROR_CODE)
    except NotImplementedError:
      response_string = _write_error_packet(dns_query_data, _NOT_IMPLEMENTED_CODE)
    except RefusedError:
      response_string = _write_error_packet(dns_query_data, _REFUSED_CODE)
    # TODO: Should there be an additional except block here, so that if an 
    # unknown exception occurs, we just assume that it's a ServerFailedError?
    # I don't think that would be an incorrect policy decision, but it might 
    # make debugging very tricky in some cases.

    # Serialize the dictionary back in to string form, so that we can send it 
    # to the user. Of course, we should only do this if we haven't gotten 
    # an error.
    if response_dict == None: # Added in inver 3.3
      return None
    if cbfunc_success:
      response_string = convert_dictionary_to_packet(response_dict)

  # Return the response we've been instructed to send.
  return response_string




def _check_malformed_packet(dns_query_data):
  """
  <Purpose>
    This function checks for macroscopic problems with the packet, such as 
    being less than 12 octets long. (Meaning, there isn't even a complete 
    header, so we'd know that the packet's malformed.) If this happens, 
    we don't have a lot of options other than to return a generic response 
    to the user indicating that their packet was malformed.

    The goal here isn't to catch subtle problems with the packet. Rather, this 
    method should act as a filter to get rid of packets which are all kinds of 
    wrong.

  <Arguments>
    A raw packet received from a listen port in string form.

  <Exceptions>
    None

  <Side Effects>
    None

  <Returns>
    A boolean indicating whether a critical problem was encountered (false) or 
    that the packet parsed properly (true).
  """
  # Since DNS headers are 12 bytes long, any packet with fewer than that is 
  # severely malformed. We check for less than 13, however, since we also 
  # require a question section after the header. If there is no 13th bit, we 
  # may as well just not parse the header at all.
  if len(dns_query_data) < 13:
    return False

  try:
    convert_packet_to_dictionary(dns_query_data)
  except Exception:
    return False


  return True
    
  """ The following is not the responsibility of dnsserver to determine. 
      If the server using this utility decides that these are unacceptable 
      criteria, it falls to them to dismiss the packet as malformed.

  # There are a few things we can do here to ensure that the packet isn't 
  # malformed. The first of which is checking that answer_count, nscount, 
  # and arcount in the header are equal to zero. If they aren't, the 
  # packet is malformed.

  # answer_count != 0 is not valid in queries, so if we detect that situation, 
  # we flag the packet as bad.
  if _charpair_to_int16(dns_query_data[6:8]) != 0:
    return False

  # nscount != 0 is not vaid in queries, so if we detect that, we indicate 
  # that the packet was malformed.
  if _charpair_to_int16(dns_query_data[8:10]) != 0:
    return False

  # arcount != 0 is not valid in queries, so if we detect as much, we return 
  # false to indicate that there's something wrong with the packet.
  if _charpair_to_int16(dns_query_data[10:12]) != 0:
    return False

  """

  # Next, we will do a dry run of parsing through the question section, 
  # similar to the actual read we do later on. This is a dragnet for 
  # possible errors.

    
  # Set the iterator for the dry run to the first byte after the header
  read_location = 12
  
  # While DNS would require us to refuse messages where label_length is 
  # ever greater than 63 octets, for our purposes, we can let it slide.
  # This won't cause an out of bounds error, since we verified the existence 
  # of the 13th bit awhile back.
  label_length = ord(dns_query_data[read_location])

  # Advance read_location by one, to account for the byte we just read.
  read_location += 1

  # We'll pretend that we're reading the data, though this is never used.
  unused_data = ""
  
  # This block is large, but we're only catching one type of exception, so 
  # it shouldn't interfere with debugging.
  try:
    # We iterate through until we read in a label length equal to zero, since by 
    # convention DNS hostnames terminate with a zero-octet.
    while label_length != 0:

      # Before blindly reading, we should ensure that data still exists. If we 
      # have unexpectedly hit end of input, we should flag the packet as bad.
      if len(dns_query_data) < read_location + label_length + 1:
        return False

      # Write the indicated label in to the question_name element of packet_dict.
      unused_data += dns_query_data[read_location:read_location + label_length]

      # Advance read_location by the amount we just read in.
      read_location += label_length

      # Read in the length of the next label. We don't have to worry about errors 
      # here, since our sanitizing method already passed this packet as DNS 
      # compliant.
      label_length = ord(dns_query_data[read_location])

      # Advance read_location by one, to account for the label length byte we 
      # read in.
      read_location += 1

  except IndexError:
    return False

  # There's no need to read in the question type or class; we just need to 
  # verify that there are four more bytes in which they probably exist.
  if len(dns_query_data) < read_location + 4:
    return False

  return True




def _write_error_packet(dns_query_data, error_code):
  """
  <Purpose>
    If _check_malformed_packet flags a packet as being fatally malformed, 
    this method generates an error packet to send to the user which might help 
    them figure out what they're doing wrong.

  <Arguments>
    dns_query_data
      The raw packet indicated as being malformed. This will be in string form, 
      without modification since having been read in from the network.
    
    error_code
      The DNS error code indicating what went wrong. As a reference, we use 
      the following error_codes (integers) :
      
    1 Format error - Packet was malformed
    2 Server failure - Server was unable to complete request
    3 Name Error - NXDOMAIN. Indicates that the name requested doesn't exist.
    4 Not Implemented - The server does not support the specified functionality.
    5 Refused - The server actively refused the connection.

  <Exceptions>
    None

  <Side Effects>
    None

  <Returns>
    A packet ready to be sent to the user, in string form.
  """
  # All we have to do in this method is rewrite the third and fourth octets 
  # of the message the user sent us.

  # First declare our new octet value to be 128, indicating that this is a 
  # response. We'll add more soon.
  three_octet = 128

  # Indicate that this is an authoritative information source.
  three_octet += 4
  
  # If the user requested recursion, we should keep that information in 
  # the packet.
  if ord(dns_query_data[2]) & 1 != 0:
    three_octet += 1

  # Indicate that we will be accepting recursion requests as a matter of course.
  four_octet = 128

  # If the client left the authenticated data bit true, we should preserve that.
  if ord(dns_query_data[3]) & 32 != 0:
    four_octet += 32

  # If the client left the checking disabled bit true, we preserve that too.
  if ord(dns_query_data[3]) & 16 != 0:
    four_octet += 16

  # We always tack on the error code.
  four_octet += error_code

  # Convert the new bytes we've produced to string form.
  new_bytes = chr(three_octet) + chr(four_octet)

  # Overwrite the old header with the new one, and return.
  return dns_query_data[:2] + new_bytes + dns_query_data[4:]