dnsruby 1.26 → 1.30

data/DNSSEC

@@ -0,0 +1,19 @@
+DNSSEC support in Dnsruby
+=========================
+
+DNSSEC defines a set of security extensions to DNS which provide a way for a resolver to verify cryptographically the DNS RRSets returned by an upstream resolver. The main standard is defined in RFCs 4033, 4034 and 4035.
+
+Dnsruby provides a recursive, validating security-aware stub resolver which maintains a cache of trusted keys and verifies RRSIG-signed messages with those keys (adding new trusted keys from signed DNSKEY RRSets and DS records). If dnsruby does not currently have the required key, it will attempt to walk the tree from the nearest known trusted key.
+
+The dnssec security status of a message is stored in Message#security_level (defined by Message::SecurityLevel).
+
+It is possible to tell Dnsruby to use a Recursor or a defined (or system default) Resolver to perform the validation. The default is to use a Recursor, as many systems are behind dodgy servers which mangle the DNS records. Using a Recursor means that only authoritative nameservers are queried for the DNSSEC records.
+
+In the absence of a signed root, Dnsruby has no trust anchor to validate messages against. It is possible to manually configure dnsruby with individual trust ancors. It is also possible to import a trust anchor repository (such as the one maintained by IANA), and configure the ISC DLV registry. Dnsruby contains basic methods to do this, although they are not currently secured. Clients are recommended to develop their own means of obtaining the initial trust anchors.
+
+It is possible to turn off dnssec validation on a per-message basis. Simply set Message#do_validation to false.
+
+DNSSEC is on by default - if desired, you can turn it off with the dnssec flag in Dnsruby::(Single)Resolver if desired. EDNS0 support is also enabled by default - if desired, you can turn this off by setting the Dnsruby::(Single)Resolver#udp_packet_size property to be 512. There should generally be no need to do this.
+
+Dnsruby maintains a cache of responses, and a cache of trusted keys. Once the initial keys have been downloaded, and a set of trusted keys built up, very little overhead is required to enjoy the benefits of DNSSEC. There is, however, some initial cost (to build up the caches).
+

data/EVENTMACHINE

@@ -1,64 +1 @@
-Using the Dnsruby EventMachine code
-===============================================================
-
-Dnsruby can use either its inbuilt (pure Ruby) event loop, or
-EventMachine (a native extension to Ruby which must be installed
-on the local platform).
-
-
-Configuring Dnsruby to use EventMachine
-----------------------------------------------------------------
-
-I left a couple of switches in Dnsruby::Resolver :
-
-    Dnsruby::Resolver.use_eventmachine(on=true)
-    Dnsruby::Resolver.start_eventmachine_loop(on=true)
-
-The first of these tells Dnsruby to use EventMachine, rather
- than its own event loop.
-
-The second tells Dnsruby whether to start the EventMachine loop
-or not. 
-
-If standard Dnsruby client code is used, then Dnsruby needs to 
-call EventMachine::run{} in order to start the EventMachine loop.
-However, if more than one EventMachine loop is started in a Ruby
-process, then the process terminates. 
-
-So, if client code is written in an EventMachine style, contained
-in an EventMachine::run{} call, then it will need to tell Dnsruby 
-NOT to start the EventMachine loop (on pain of sudden death!).
-
-
-
-Example code
-----------------------------------------------------------------
-
-Here is an example of using the code in an EventMachine style :
-
-require 'Dnsruby'
-require 'eventmachine'
-res = Dnsruby::Resolver.new
-Dnsruby::Resolver.use_eventmachine
-Dnsruby::Resolver.start_eventmachine_loop(false)
-EventMachine::run {
-  df = res.send_async(Dnsruby::Message.new("example.com"))
-  df.callback {|msg| 
-     puts "Response : #{msg}"
-     EM.stop}
-  df.errback {|msg, err|
-     puts "Response : #{msg}"
-     puts "Error: #{err}"
-     EM.stop}
-}
-
-And an example in a normal Dnsruby style :
-
-require 'Dnsruby'
-res = Dnsruby::Resolver.new
-Dnsruby::Resolver.use_eventmachine
-Dnsruby::Resolver.start_eventmachine_loop(true) # default
-q = Queue.new
-id = res.send_async(Dnsruby::Message.new("example.com"),q)
-id, response, error = q.pop
-
+Dnsruby no longer supports EventMachine - the inbuilt select loop now works on all platforms.

data/EXAMPLES

@@ -0,0 +1,124 @@
+# This file shows how to do common tasks with Dnsruby :
+
+require 'dnsruby'
+include Dnsruby
+
+# Use the system configured nameservers to run a query
+res = Resolver.new
+ret = res.query("example.com") # Defaults to A record
+a_recs = ret.answer.rrset("A")
+
+# Use a defined nameserver to run an asynchronous query
+# with no recursion
+res = Resolver.new({:nameserver => ["a.iana-servers.net",
+        "b.iana-servers.net"]})
+queue = Queue.new
+m = Message.new("example.com", Types.NS)
+m.header.rd = false
+res.send_async(m, queue, 1)
+# ... do some other stuff ...
+id, reply, error = queue.pop
+if (error)
+  print "Error : #{error}\n"
+else
+  # See where the answer came from
+  print "Got response from : #{reply.answerfrom}, #{reply.answerip}\n"
+end
+
+# Use a Recursor to recursively query authoritative nameservers,
+# starting from the root. Note that a cache of authoritative servers
+# is built up for use by future queries by any Recursors.
+rec = Recursor.new
+ret = rec.query("uk-dnssec.nic.uk", "NS")
+
+# Ask Dnsruby to send the query without using the cache.
+m.do_caching = false
+ret = res.send_message(m)
+
+# Ask Dnsruby to send a Message without doing any pre- or post-processing
+ret = res.send_plain_message(Message.new("example.com"))
+
+# Send a TSIG signed dynamic update to a resolver
+# and verify the response
+res = Dnsruby::Resolver.new("ns0.validation-test-servers.nominet.org.uk")
+res.dnssec = false
+tsig = Dnsruby::RR.create({
+        :name        => "rubytsig",
+        :type        => "TSIG",
+        :ttl         => 0,
+        :klass       => "ANY",
+        :algorithm   => "hmac-md5",
+        :fudge       => 300,
+        :key         => "8n6gugn4aJ7MazyNlMccGKH1WxD2B3UvN/O/RA6iBupO2/03u9CTa3Ewz3gBWTSBCH3crY4Kk+tigNdeJBAvrw==",
+        :error       => 0
+      })
+update = Dnsruby::Update.new("validation-test-servers.nominet.org.uk")
+# ... add stuff to the update
+update.absent("notthere.update.validation-test-servers.nominet.org.uk", 'TXT')
+tsig.apply(update)
+response = res.send_message(update)
+print "TSIG response was verified? : #{response.verified?}\n"
+
+#
+# DNSSEC stuff
+#
+
+# Load the ISC DLV key and query some signed zones
+dlv_key = RR.create("dlv.isc.org. IN DNSKEY 257 3 5 BEAAAAPHMu/5onzrEE7z1egmhg/WPO0+juoZrW3euWEn4MxDCE1+lLy2 brhQv5rN32RKtMzX6Mj70jdzeND4XknW58dnJNPCxn8+jAGl2FZLK8t+ 1uq4W+nnA3qO2+DL+k6BD4mewMLbIYFwe0PG73Te9fZ2kJb56dhgMde5 ymX4BI/oQ+cAK50/xvJv00Frf8kw6ucMTwFlgPe+jnGxPPEmHAte/URk Y62ZfkLoBAADLHQ9IrS2tryAe7mbBZVcOwIeU/Rw/mRx/vwwMCTgNboM QKtUdvNXDrYJDSHZws3xiRXF1Rf+al9UmZfSav/4NWLKjHzpT59k/VSt TDN0YUuWrBNh")
+Dnssec.add_dlv_key(dlv_key)
+res = Recursor.new
+ret = res.query("frobbit.se", "NS")
+print "Security level for signed zone from DLV : #{ret.security_level}\n"
+frobbit_servers = ret.answer.rrset("frobbit.se", Types.NS)
+
+
+# and query for a zone which is not signed
+r = Resolver.new
+ret = r.query("ed.ac.uk")
+print "Security level of unsigned zone : #{ret.security_level}\n"
+
+res = Resolver.new
+frobbit_servers.rrs.each {|s| print "Adding nameserver : #{s.nsdname}\n"; res.add_server(s.nsdname)}
+
+# and some non-existent domains in signed ones
+res.send_async(Message.new("notthere.frobbit.se"), queue, 2)
+id, reply, error = queue.pop
+print "Error returned from non-existent name in signed zone : #{error}, security level : #{reply.security_level}\n"
+
+# Clear the keys and caches
+Dnsruby::Dnssec.clear_trusted_keys
+Dnsruby::Dnssec.clear_trust_anchors
+Dnsruby::InternalResolver.clear_caches
+
+
+# Load the IANA TAR and query some signed zones
+Dnssec.load_itar
+ret = res.query("frobbit.se", "NS")
+print "Security level for signed zone from DLV : #{ret.security_level}\n"
+
+# Query a name with no validation to be performed
+m = Message.new("frobbit.se", "MX")
+m.do_validation = false
+ret = res.send_message(m)
+print "Security level of secure domain with no validation : #{ret.security_level}\n"
+
+# Clear the keys and caches
+Dnsruby::Dnssec.clear_trusted_keys
+Dnsruby::Dnssec.clear_trust_anchors
+Dnsruby::InternalResolver.clear_caches
+
+# Load a specific trust anchor and query some signed zones
+trusted_key = Dnsruby::RR.create({:name => "uk-dnssec.nic.uk.",
+        :type => Dnsruby::Types.DNSKEY,
+        :flags => 257,
+        :protocol => 3,
+        :algorithm => 5,
+        :key=> "AQPJO6LjrCHhzSF9PIVV7YoQ8iE31FXvghx+14E+jsv4uWJR9jLrxMYm sFOGAKWhiis832ISbPTYtF8sxbNVEotgf9eePruAFPIg6ZixG4yMO9XG LXmcKTQ/cVudqkU00V7M0cUzsYrhc4gPH/NKfQJBC5dbBkbIXJkksPLv Fe8lReKYqocYP6Bng1eBTtkA+N+6mSXzCwSApbNysFnm6yfQwtKlr75p m+pd0/Um+uBkR4nJQGYNt0mPuw4QVBu1TfF5mQYIFoDYASLiDQpvNRN3 US0U5DEG9mARulKSSw448urHvOBwT9Gx5qF2NE4H9ySjOdftjpj62kjb Lmc8/v+z"
+      })
+Dnssec.add_trust_anchor(trusted_key)
+res = Dnsruby::Resolver.new("dnssec.nominet.org.uk")
+r = res.query("aaa.bigzone.uk-dnssec.nic.uk", Dnsruby::Types.DNSKEY)
+print "Security level of signed zone under manually install trusted key : #{r.security_level}\n"
+
+# See if we are using a Recursor for DNSSEC queries
+print "Using recursion to validate DNSSEC responses? : #{Dnssec.do_validation_with_recursor?}\n"

data/README

@@ -17,7 +17,7 @@ The following is a (non-exhaustive) list of features :
 o Implemented RRs :  A, AAAA, AFSDB, ANY, CERT, CNAME, DNAME,
      HINFO, ISDN, LOC, MB, MG, MINFO, MR, MX, NAPTR, NS, NSAP,
      OPT, PTR, PX, RP, RT, SOA, SPF, SRV, TKEY, TSIG, TXT, WKS,
-     X25
+     X25, DNSKEY, RRSIG, NSEC, NSEC3, NSEC3PARAM, DS, DLV
 
 o Generic RR types supported (RFC3597)
 
@@ -25,7 +25,7 @@ o (Signed) Zone transfer (AXFR and IXFR) supported
 
 o (Signed) Dyamic updates supported
 
-o DNSSEC support in progress
+o DNSSEC validation supported
 
 Dependencies
 ============
@@ -38,10 +38,6 @@ the test code will not run the tests which require it. Code which
 attempts to use the library (if it is not present) will raise an
 exception.
 
-If EventMachine is to be used, then the EventMachine library must
-be present on the platform. If the EventMachine library is not 
-present then the test code will not run the EventMachine tests.
-
 Demo code
 =========
 

data/demo/axfr.rb

@@ -43,8 +43,8 @@
 #      Michael Fuhr <mike@fuhr.org>
 #      
 
-require 'GetoptLong'
-require 'Dnsruby'
+require 'getoptLong'
+require 'dnsruby'
 
 #------------------------------------------------------------------------------
 # Read any command-line options and check syntax.

data/demo/check_soa.rb

@@ -24,7 +24,7 @@
 #
 #axfr, check_zone, mresolv, mx, perldig, Net::DNS
 
-require 'Dnsruby'
+require 'dnsruby'
 
 #------------------------------------------------------------------------------
 # Get the domain from the command line.

data/demo/check_zone.rb

@@ -26,8 +26,8 @@
 #
 
 
-require 'Dnsruby'
-require 'GetoptLong'
+require 'dnsruby'
+require 'getoptLong'
 
 def check_domain(args)
   domain = args[0]

data/demo/digdlv.rb

@@ -0,0 +1,65 @@
+#= NAME
+#
+#digdlv - Ruby script to perform DNS queries, validated against the ISC DLV
+#registry.
+#
+#= SYNOPSIS
+#
+#digdlv name [ type [ class ] ]
+#
+#= DESCRIPTION
+#
+#Performs a DNS query on the given name.  The record type
+#and class can also be specified; if left blank they default
+#to A and IN.
+#The program firstly loads the DLV zone signing key. Then, the
+#requested DNS query is performed recursively. The response is then validated
+#- the DLV registry is searched for the keys of the closest ancestor
+#of the query name, and the chain of trust is followed to prove
+#that the DNSSEC records are correct, or that we do not expect the
+#response to be signed.
+#
+#= AUTHOR
+#
+#Michael Fuhr <mike@fuhr.org>
+#Alex D <alexd@nominet.org.uk>
+
+require 'dnsruby'
+include Dnsruby
+
+raise RuntimeError, "Usage: #{$0}  name [ type [ class ] ]\n" unless (ARGV.length >= 1) && (ARGV.length <= 3)
+
+
+res = Dnsruby::Recursor.new
+zt=Dnsruby::ZoneTransfer.new
+  
+dlv_key = RR.create("dlv.isc.org. IN DNSKEY 257 3 5 BEAAAAPHMu/5onzrEE7z1egmhg/WPO0+juoZrW3euWEn4MxDCE1+lLy2 brhQv5rN32RKtMzX6Mj70jdzeND4XknW58dnJNPCxn8+jAGl2FZLK8t+ 1uq4W+nnA3qO2+DL+k6BD4mewMLbIYFwe0PG73Te9fZ2kJb56dhgMde5 ymX4BI/oQ+cAK50/xvJv00Frf8kw6ucMTwFlgPe+jnGxPPEmHAte/URk Y62ZfkLoBAADLHQ9IrS2tryAe7mbBZVcOwIeU/Rw/mRx/vwwMCTgNboM QKtUdvNXDrYJDSHZws3xiRXF1Rf+al9UmZfSav/4NWLKjHzpT59k/VSt TDN0YUuWrBNh")
+Dnssec.add_dlv_key(dlv_key)
+
+
+name, type, klass = ARGV
+type  ||= "A"
+klass ||= "IN"
+  
+if (type.upcase == "AXFR")
+  rrs = zt.transfer(name) # , klass)
+    
+  if (rrs)
+    rrs.each do |rr|
+      print rr.to_s + "\n"
+    end
+  else
+    raise RuntimeError, "zone transfer failed: ", res.errorstring, "\n"
+  end
+    
+else
+
+#  Dnsruby::TheLog.level=Logger::DEBUG
+  begin
+    answer = nil
+    answer = res.query(name, type, klass)
+    print answer
+  rescue Exception => e
+    print "query failed: #{e}\n"
+  end
+end

data/demo/digitar.rb

@@ -0,0 +1,62 @@
+#= NAME
+#
+#digitar - Ruby script to perform DNS queries, validated against the IANA TAR
+#(trust anchor repository).
+#
+#= SYNOPSIS
+#
+#digitar name [ type [ class ] ]
+#
+#= DESCRIPTION
+#
+#Performs a DNS query on the given name.  The record type
+#and class can also be specified; if left blank they default
+#to A and IN. The program firstly performs the requested DNS
+# query. The response is then validated
+#- the ITAR is searched for the keys of the closest ancestor
+#of the query name, and the chain of trust is followed to prove
+#that the DNSSEC records are correct, or that we do not expect the
+#response to be signed.
+#
+#= AUTHOR
+#
+#Michael Fuhr <mike@fuhr.org>
+#Alex D <alexd@nominet.org.uk>
+
+require 'dnsruby'
+include Dnsruby
+
+raise RuntimeError, "Usage: #{$0} name [ type [ class ] ]\n" unless (ARGV.length >= 1) && (ARGV.length <= 3)
+
+Dnssec.load_itar
+res = Dnsruby::Recursor.new
+zt=Dnsruby::ZoneTransfer.new
+  
+  
+#    Dnsruby::TheLog.level=Logger::DEBUG
+
+name, type, klass = ARGV
+type  ||= "A"
+klass ||= "IN"
+  
+if (type.upcase == "AXFR")
+  rrs = zt.transfer(name) # , klass)
+    
+  if (rrs)
+    rrs.each do |rr|
+      print rr.to_s + "\n"
+    end
+  else
+    raise RuntimeError, "zone transfer failed: ", res.errorstring, "\n"
+  end
+    
+else
+
+  begin
+    answer = nil
+    answer = res.query(name, type, klass)
+    print answer
+  rescue Exception => e
+    print "query failed: #{e}\n"
+  end
+end

data/demo/mresolv.rb

@@ -13,7 +13,7 @@
 #*-t timeout : Set the query timeout for each name in seconds.
 
 require 'dnsruby'
-require 'GetoptLong'
+require 'getoptLong'
 
 opts = GetoptLong.new(["-d", GetoptLong::NO_ARGUMENT],
   ["-n", GetoptLong::REQUIRED_ARGUMENT],

data/demo/mx.rb

@@ -1,4 +1,4 @@
-require 'Dnsruby'
+require 'dnsruby'
 
 #= NAME
 #

data/demo/rubydig.rb

@@ -18,16 +18,21 @@
 #
 
 require 'dnsruby'
+include Dnsruby
 
 res = Dnsruby::Resolver.new
 zt=Dnsruby::ZoneTransfer.new
   
 if (ARGV && (ARGV[0] =~ /^@/))
-  nameserver = ARGV.shift 
+  nameserver = ARGV.shift
+  if (nameserver == "@auth")
+    res = Dnsruby::Recursor.new
+  else
   print "Setting nameserver : #{nameserver}\n"
   res.nameserver=(nameserver.sub(/^@/, ""))
   print "nameservers = #{res.config.nameserver}\n"
   zt.server=(nameserver.sub(/^@/, ""))
+  end
 end
 
 raise RuntimeError, "Usage: #{$0} [ \@nameserver ] name [ type [ class ] ]\n" unless (ARGV.length >= 1) && (ARGV.length <= 3)
@@ -49,7 +54,9 @@ if (type.upcase == "AXFR")
     
 else
 
+#    Dnsruby::TheLog.level=Logger::DEBUG
   begin
+    answer = nil
     answer = res.query(name, type, klass)
     print answer
   rescue Exception => e