dnsruby 1.74.0 → 2.0.0

data/RELEASE_NOTES.md

@@ -1,5 +1,307 @@
 # Release Notes
 
+## v2.0.0
+
+Dnsruby 2.0 adds SVCB and HTTPS records and support for Ed25519 and Ed448 DNSSEC
+signatures. It makes queries, TCP connections, zone transfers and DNSSEC
+validation more reliable. It also bounds caches and validation work, updates
+the root trust anchors, and improves performance when many queries are in
+progress.
+
+Most existing query code can stay as it is. Before upgrading, check the Ruby
+requirement, TSIG settings and record persistence described below, followed by
+any DNSSEC or timeout settings your application uses.
+
+### Compatibility with 1.74.0
+
+* **Ruby 3.0 or later is required.** Upgrade older Ruby installations before
+  installing Dnsruby 2.0.
+* **TSIG now defaults to HMAC-SHA256.** If you previously omitted the algorithm
+  and your server uses HMAC-MD5, update the key on both sides or select MD5
+  explicitly: `resolver.tsig = key_name, secret, 'hmac-md5'`. Explicit MD5
+  settings still work, but MD5 is prohibited by RFC 8945 section 6. Selecting it
+  logs one warning per process at WARN level; the default log level is FATAL.
+  SHA-1 remains supported, and SHA-256 is recommended. There is no automatic
+  fallback to another algorithm. See [updating TSIG keys](README.md#updating-tsig-keys)
+  for SHA-256 settings that also work with 1.74.0.
+* **Automatically generated record classes no longer support Marshal/YAML
+  persistence.** Unknown type/class pairs now use a cache of at most 256 classes,
+  and those classes are no longer permanent Ruby constants. Ordinary named
+  classes such as `Dnsruby::RR::IN::A` are unaffected. Records and classes your
+  application holds remain usable even after their automatic `ClassHash` entry
+  is evicted. To customise a generated class, keep the result of
+  `Dnsruby::RR.get_class(type, klass)` and use `class_eval`. For a fixed set of
+  application-defined types that needs permanent names and normal Marshal
+  behavior, call `Dnsruby::RR::Generic.create(type, klass)` before creating records. These
+  explicit registrations stay in memory: do not use them for arbitrary types
+  received from the network. The 256-class limit excludes explicit registrations
+  and objects retained by your application or the response cache.
+* **DNSSEC uses current algorithm policy.** Resolver validation treats SHA-1
+  signing algorithms 5 and 7 as unsupported under RFC 9905. Answers relying
+  solely on them become `INSECURE`, meaning they are not protected by an
+  accepted DNSSEC chain. Explicit cryptographic verification and historical
+  record decoding remain available. DSA algorithms 3 and 6 are also
+  unsupported for validation, as required by RFC 8624. An authenticated
+  delegation with only unsupported DS algorithms or digests is insecure; a
+  mixed set still requires validation through a supported DS. Within an
+  authenticated DS set, SHA-256 takes precedence over SHA-1. `DS.from_key` now
+  defaults to SHA-256 and rejects new DS records using SHA-1 digests or signing
+  algorithms 5 or 7. RSA keys with noncanonical encodings or sizes outside the
+  protocol limits are rejected. See [DNSSEC algorithm policy](README.md#dnssec-algorithm-policy).
+  Ed25519 and Ed448 validation require version 3.0 or later of the `openssl` gem and
+  an OpenSSL provider that supports it. Otherwise it follows the same rules
+  as other unsupported algorithms.
+* **DNSSEC validation has work and time limits.** The defaults are 64 signature
+  attempts, 100,000 work units and five seconds per answer, including queries
+  needed to follow the chain of trust. A limit raises `ValidationLimitError`,
+  a subclass of `VerifyError`; it never turns a failed validation into an
+  insecure answer. Up to four workers validate responses at once, with another
+  64 responses waiting. Applications with unusual validation workloads can
+  [adjust these limits](README.md#dnssec-validation-limits).
+* **Recursive lookups have shared discovery limits.** A complete lookup now
+  defaults to 30 seconds, 128 transmission attempts, 256 discovery work units
+  and eight address-discovery worker threads. Supporting lookups share these
+  limits, and repeated dependencies on the same path are skipped. A shorter
+  Resolver timeout still takes precedence. Applications can configure
+  `Recursor#recursion_limits`; work or transmission exhaustion raises
+  `RecursionLimitError`. See [recursive lookup limits](README.md#recursive-lookup-limits).
+* **Retries, failures and transfers have bounded lifetimes.** For each question,
+  RFC 9520 limits attempts to three per server address and transport, including
+  protocol retries; `retry_times` values above three are capped. Completed
+  failures are cached for one second, so an immediate repeat may return the
+  same error without a new exchange. The total `query_timeout` now includes
+  local DNSSEC validation. Reusable TCP connections close after ten idle
+  seconds by default; set `tcp_idle_timeout` to a positive number of seconds
+  to change this. Connections with outstanding queries stay open. ZoneTransfer
+  allows 30 seconds by default to read or write each complete frame; increase
+  `io_timeout` for slower transfers. Its optional `transfer_timeout` limits a
+  complete attempt with one server. See [response caching and retries](README.md#response-caching-and-retries)
+  and [zone transfer deadlines](README.md#zone-transfer-deadlines).
+* **The default EDNS UDP payload size is 1232 bytes, down from 4096.** This
+  reduces fragmentation risk but can cause more TCP retries. Explicit sizes
+  such as 4096 still work. DNSSEC raises smaller limits to 1220 bytes, the
+  minimum in RFC 4035 section 4.1. The 1232-byte default is permitted by
+  RFC 10001 section 3.2.
+* **SVCB and HTTPS are now parsed records.** Types 64 and 65 use their registered
+  names in text output and expose `priority`, `target` and `params`. Their
+  `data` and `rdata` readers return binary RDATA snapshots reflecting those
+  fields, and `rdlength` reports the length. To replace the data, use `data=`,
+  `rdata=` or `RR.create` with `rdata:`. The original decoded `@rdata` remains
+  available for existing callers such as JSONDNS, but this private field does
+  not track later edits. Malformed escapes are rejected. ALPN and DoC path
+  lists permit only escaped commas and backslashes at their second escape
+  layer; the `mandatory`, `port`, `ipv4hint`, `ech` and `ipv6hint` mnemonics
+  do not permit presentation escapes. Numeric `keyNNNNN` forms still accept
+  escaped wire octets. [PR #222](https://github.com/alexdalitz/dnsruby/pull/222).
+* **Some invalid names and numeric values are now rejected.** DNS names longer
+  than 255 wire octets raise `ResolvError`, including some 256- and 257-octet
+  names previously accepted. Numeric type/class constructors and RRSIG
+  type-covered setters require values in 0–65535.
+  [PR #223](https://github.com/alexdalitz/dnsruby/pull/223).
+* **Numeric and IPv6 text remain predictable.** Numeric spellings retain their
+  presentation on each object but no longer register global aliases or change
+  a code's preferred name. Explicit `Types.add_pair` and `Classes.add_pair`
+  aliases still work. Existing `IPv6#to_s`, `#inspect` and record presentations
+  keep their 1.74.0 output; use `IPv6#to_s_canonical` for RFC 5952 formatting.
+* **The simpleidn range is now `>= 0.2.1`, `< 0.4.0`.** Updating from 0.2.x can
+  change Unicode-to-DNS name conversion. Check the results if your application
+  depends on exact converted names.
+  [PR #224](https://github.com/alexdalitz/dnsruby/pull/224).
+
+Zone files now resolve relative `$ORIGIN` directives and SOA names against the
+current origin, including names with an escaped final dot. TXT records preserve
+UTF-8 and escaped bytes through wire encoding, and their 255-octet string limit
+is checked before writing. ZoneReader treats nonnumeric escapes literally under
+DNS zone-file rules, including `\n` as `n`; direct `RR::TXT.parse` and
+`RR.create` retain their legacy C-style escapes for compatibility. Escaped
+whitespace also works in `$ORIGIN`, MX and NSEC names.
+DS, CDS and DLV records preserve private algorithm
+numbers and unknown digest numbers. Name compression also keeps literal dots
+inside labels distinct from the dots that separate labels.
+
+### More reliable queries and transfers
+
+* TCP pipelining handles concurrent sends, immediate replies, partial writes
+  and disconnected servers. Connection setup, writes and waiting for a pipeline
+  slot all respect the controlling query's deadline and cancellation. Malformed
+  replies no longer interrupt other queries or cause endless TCP retries.
+  UDP reads cannot block after a readiness notification, and changes to TCP
+  pipelining take effect consistently on subsequent attempts. Updating a source
+  port pool no longer briefly exposes an empty pool to concurrent sends.
+  Invalid replacements leave the previous configuration intact, and an occupied
+  port no longer prevents a send from trying the other configured ports.
+  Each attempt retains one transport configuration snapshot through connection
+  setup, reply matching and caching. Adding an explicit source port replaces
+  the default `[0]` pool; zero cannot be mixed with explicit ports.
+  A zero retry delay keeps every scheduled nameserver attempt.
+  [#155](https://github.com/alexdalitz/dnsruby/issues/155).
+* Cancellation and timeouts wake waiting queries promptly, including while
+  validation or nameserver discovery is running. Late replies or callbacks
+  cannot complete an expired query or affect a later query that reuses its ID.
+  Once validation starts, another nameserver's reply cannot replace the accepted
+  answer. Closing a client's completion Queue no longer interrupts other
+  resolvers. After `fork`, the child uses fresh connections and query state;
+  the parent's pending work remains with the parent.
+* Ordinary queries reject replies with the wrong ID, opcode or query/response
+  flag; `send_raw` retains its existing behavior. UDP-to-TCP fallback still
+  respects `no_tcp` and `ignore_truncation`. Retrying without optional EDNS keeps
+  the current transport, and TCP can handle a FORMERR reply without a question;
+  UDP still requires a matching question. Queries requiring local DNSSEC
+  validation keep EDNS enabled. Setting DO on an existing OPT preserves its
+  payload size, options and other flags.
+* Hostname nameservers no longer cause recursive configuration hangs. Existing
+  queries continue while replacement nameservers are resolved, and concurrent
+  configuration changes are preserved. IPv6 link-local nameservers accept
+  interface zones such as `fe80::1%eth0`, including in `resolv.conf`. Recursive
+  discovery tries other nameservers and address families after ordinary lookup
+  failures, within the same cancellation and validation limits. A Recursor
+  honors the transport and source settings of its supplied Resolver and applies
+  its query timeout to the complete lookup. Changes to DNSSEC root hints take
+  effect on subsequent lookups. Root hints are also refreshed when all their
+  cached addresses expire, including during a lookup. Root NS TTLs separately
+  bound bootstrap reuse, partial priming replies trigger discovery of missing
+  root addresses, and zero-TTL priming addresses remain usable by their current
+  lookup. Ancestor lookup preserves escaped label boundaries and relative names.
+  [#179](https://github.com/alexdalitz/dnsruby/issues/179),
+  [#184](https://github.com/alexdalitz/dnsruby/issues/184),
+  [PR #221](https://github.com/alexdalitz/dnsruby/pull/221).
+* A SingleResolver keeps only its selected server after initialization and
+  later `server=` changes. A Resolver with `retry_times = 0` completes with
+  a timeout immediately instead of leaving an empty retry plan waiting.
+* Zone transfers complete partial writes, check response envelopes and require
+  matching opening and closing SOAs. TSIG transfers authenticate the whole
+  sequence, permit up to 99 unsigned messages between signatures and reject
+  decreasing signed timestamps. Reusing a ZoneTransfer gives each request a
+  fresh signing time unless one was set explicitly.
+
+### Authentication, DNSSEC and caching
+
+* Positive answers are kept separate for different upstream servers, ports,
+  source settings and query options. Truncated replies are not cached. A
+  recursor follows one delegation that encloses the question and still accepts
+  valid sibling glue from the parent zone.
+
+* TSIG queries always require a fresh authenticated exchange and bypass the
+  shared response cache. Unsigned replies and invalid MACs are ignored while
+  waiting for a valid reply; if none arrives, the timeout reports the
+  authentication error. Authenticated BADTIME and BADTRUNC replies report the
+  server's error. Queries are prepared before signing, including when the key
+  is set on a Message; already signed messages retain their headers and OPT
+  record. Verification checks the MAC before timestamps and truncation policy,
+  and uses the Original ID as required by RFC 8945. Valid truncated MACs are
+  supported; `mac_length` sets the signing length and minimum accepted length
+  in octets. Malformed TSIG records are rejected, and key secrets are no longer
+  written to the log.
+* Root trust anchors include KSK-2024 (38696) and remove revoked KSK-2010
+  (19036). `Dnssec.reset` restores the current anchors.
+  `Dnssec.clear_trusted_keys` clears learned keys and DS/DLV anchors while
+  retaining configured DNSKEY anchors. Removing or expiring a configured anchor
+  also removes keys learned from it. Keys sharing a tag can coexist, and an
+  unusable matching key does not prevent another from validating the answer.
+  DS matching accepts the same owner name with or without a trailing dot,
+  including when the DS is a configured trust anchor.
+  Learned DNSKEY and DS records have size limits, and validation looks up only
+  matching candidates. DS anchors now honor their requested expiration times,
+  just as DNSKEY anchors do. Direct RRset verification can try another trusted
+  verifier when the first has no suitable key.
+  [#225](https://github.com/alexdalitz/dnsruby/issues/225).
+* Signed aliases can lead to authenticated unsigned zones and correctly return
+  `INSECURE`. CNAME and DNAME chains validate through to the terminal answer,
+  including negative answers, wildcard NODATA and NSEC3 Opt-Out delegations.
+  A synthesized CNAME must match its signed DNAME; valid responses that omit
+  the synthesized CNAME also work. Cross-zone aliases discover the target's
+  chain within the same validation budget. An unsigned delegation requires
+  authenticated proof: lookup failures cannot become insecure results.
+  A provisional insecure classification never suppresses a required record's
+  verification error; unsigned alias responses check every required owner and
+  the terminal name. Signed records discover their signer zones without extra
+  DS queries for each record owner.
+  Signer zones, DNSKEY Zone Key flags and DS owner/class bindings are checked.
+  A key authenticating a DNSKEY RRset must also be present in that set.
+  Missing NSEC or RRSIG bitmap bits do not prove those types absent.
+  NSEC3 records with unsupported flags are ignored as denial proofs while
+  supported records remain usable.
+* Signed Additional records are verified when their keys are available.
+  Unverifiable signed extras are removed without rejecting an independently
+  authenticated answer. Unsigned glue remains available without acquiring
+  authentication metadata from records in another section; unverified extras
+  do not enter the trusted-key cache. Validation and cancellation limits still
+  apply to optional data.
+* Validated answers and cached copies expire according to their original
+  receipt time, signatures and chain of trust. Revalidation does not renew
+  those lifetimes, and failed or BOGUS validation is never cached as successful.
+  Trying another verifier preserves a successful insecure result's authenticated
+  lifetime, so negative answers can still be cached under the default policy.
+  Bounded negative caches use the SOA lifetime required by RFC 2308; failure
+  caches follow RFC 9520. Entries respect the question class, configuration and
+  trust changes. Cancellation, raw messages, UPDATE and TSIG bypass these new
+  negative and failure caches. Recursive delegation caches are also bounded,
+  and delegation and glue-address lifetimes are tracked separately. Cached
+  child routes cannot outlive the parent route through which they were learned;
+  parent-cache eviction alone does not discard an already admitted child.
+* Changing a DNSKEY's key or algorithm clears its cached public key.
+  `verify_rrset` accepts a single DS/DLV anchor as well as an RRSet. NSEC3 and
+  NSEC3PARAM correctly handle unsigned length octets and retain salt lengths.
+
+### Records, parsing and performance
+
+* SVCB and HTTPS work in DNS messages and zone files, including relative targets,
+  numeric `keyNNNNN` parameters and escaped text. IPv6 hints use RFC 5952 text.
+* CAA accepts extensible alphanumeric tags and empty or binary values, including
+  an empty `issue` value. Wire decoding preserves the value independently of
+  presentation parsing. Private RRSIG algorithm numbers round-trip unchanged.
+  Decoded CAA records retain the historical String form of `rdata`, including
+  comparisons with text-created records and existing JSONDNS serialization.
+  Received ordinary TTLs with their high bit set become zero under RFC 2181;
+  OPT fields and TSIG's zero-TTL rule retain their special handling. Mandatory
+  names require their wire encoding, while valid empty UPDATE markers still
+  round-trip. DS, CDS and DLV equality and hashing agree for digest case variants.
+* Zone-file TTLs and SOA intervals accept combined time suffixes such as
+  `1h30m`. Both class-before-TTL and TTL-before-class formats work. Quoted,
+  escaped and multiline values preserve their punctuation, Unicode and binary
+  character strings, including single-quoted TXT and SPF values. An explicit
+  record TTL leaves the `$TTL` default in place for later records. Relative
+  names in KX, NSEC, NXT, RRSIG, IPSECKEY and HIP data now use the zone origin.
+  Zone files also accept RFC 3597 hexadecimal data for known record types
+  without changing its bytes.
+* Query scheduling, retries and cancellation avoid repeatedly scanning every
+  pending query. TCP reply matching is faster when many queries share a
+  connection. DNSSEC reuses canonical data and verifies reusable DS, DNSKEY
+  and wildcard proof sets once per message. Cache hits spend less time holding
+  the cache lock, and record parsing and numeric lookups allocate fewer
+  temporary objects. Unknown-record class handling and replacement no longer
+  accumulate memory or slow garbage collection on Ruby 3.0–3.2.
+  Name compression shares immutable label copies between suffixes, reducing
+  allocations while preserving case and escaped label boundaries.
+  RRset grouping uses an index and avoids cloning unrelated records. It
+  preserves section order and TTL normalization, and charges validation work
+  while grouping records and checking duplicates.
+  Canonical RRset sorting also avoids repeated duplicate scans, and binary
+  message decoding avoids temporary one-byte strings while retaining bounds
+  checks, compression safeguards and legacy nonbinary input behavior.
+* Recursive answers now complete CNAME and DNAME chains within the original
+  lookup's deadline and work limits. Zero-TTL nameserver addresses are usable
+  during the lookup that obtained them without entering shared caches. DNSSEC
+  work and time limits are shared across the lookup's network hops, parallel
+  address discovery and final answer validation.
+* DNSSEC validation evaluates applicable trust anchors before accepting a
+  provisional insecure result. RRSIG validity and learned-key expiration use
+  the serial-number arithmetic required for timestamps that cross the
+  32-bit boundary.
+* SRV targets, DNAME targets, RRSIG signer names and NSEC successor names are
+  encoded without name compression. Valid empty UPDATE prerequisites and
+  deletions work for all applicable record types. Zone-file owner names retain
+  escaped spaces and quotes. Decoding reuses validated compression suffixes
+  within each packet while keeping returned names independently mutable.
+* `RRSet#add` accepts another RRSet, and deleting signatures keeps the signature
+  count correct. Bulk duplicate checks avoid repeatedly encoding every record
+  already in a set while preserving mutable record behavior.
+* Replacing a SingleResolver's server preserves concurrent configuration
+  changes. TCP replies report their byte size. Zone transfers retain verified
+  BADTIME and BADTRUNC diagnostics and no longer allocate unused IXFR state
+  for each received record.
+
+
 ## v1.74.0
 
 * Resolve all configured nameservers in parallel
@@ -293,4 +595,3 @@
 * Minor bug fixes
 * IPSECKEY RR added
 * Clients can now manipulate Name::Labels
-

data/Rakefile

@@ -12,9 +12,6 @@ if ENV['RUN_EXTRA_TASK'] == 'TRUE'
     rd.main = "Dnsruby"
     #  rd.options << "--ri"
   end
-
-  require 'coveralls/rake/task'
-  Coveralls::RakeTask.new
 end
 
 def create_task(task_name, test_suite_filespec)

data/demo/axfr.rb

@@ -31,6 +31,11 @@
 # output, and stores the zone to a file.  If the zone has already been
 # stored in a file, axfr will read the file instead of performing a
 # zone transfer.
+#
+# Records with dynamically generated classes cannot be stored with Marshal.
+# Such transfers are printed without updating the cache; use -f to transfer
+# again if an older cache exists. Unreadable legacy dynamic-record caches are
+# ignored and the zone is transferred again.
 # 
 # Zones will be stored in a directory hierarchy.  For example, the
 # zone transfer for foo.bar.com will be stored in the file
@@ -68,7 +73,7 @@ unless (1..2).include?(ARGV.length)
 end
 
 
-require 'getoptLong'
+require 'getoptlong'
 require 'dnsruby'
 
 
@@ -134,16 +139,22 @@ end
 # ------------------------------------------------------------------------------
 
 if FileTest.exist?(zonefile) && !opt_f
-  zoneref = Marshal.load(File.open(zonefile))
-  if zoneref.nil?
-    raise RuntimeError, "couldn't retrieve zone from #{zonefile}: #{$!}\n"
+  begin
+    zoneref = File.open(zonefile, 'rb') { |file| Marshal.load(file) }
+    if zoneref.nil?
+      raise RuntimeError, "couldn't retrieve zone from #{zonefile}: #{$!}\n"
+    end
+  rescue ArgumentError => error
+    raise unless error.message.match?(/\Aundefined class\/module Dnsruby::RR::Generic::Type\d+_Class\d+\z/)
+    warn "Cannot read dynamic records from #{zonefile}; transferring the zone again."
+    opt_f = true
   end
 
   # ----------------------------------------------------------------------
   #  Check the SOA serial number if desired.
   # ----------------------------------------------------------------------
 
-  if opt_s
+  if opt_s && !opt_f
     serial_file = serial_zone = nil
 
     zoneref.each do |rr|
@@ -185,7 +196,14 @@ if opt_f
   if zoneref.nil?
     raise RuntimeError,  "couldn't transfer zone\n"
   end
-  Marshal.dump(zoneref, File.open(zonefile, File::CREAT | File::RDWR))
+  begin
+    cache = Marshal.dump(zoneref)
+  rescue TypeError => error
+    raise unless error.message.start_with?("can't dump anonymous class")
+    warn "Zone transferred but dynamic records cannot be cached; #{zonefile} was not changed. Use -f to transfer again."
+  else
+    File.binwrite(zonefile, cache)
+  end
 end
 
 # ------------------------------------------------------------------------------

data/demo/rubydig.rb

@@ -60,8 +60,6 @@ if ARGV[0] =~ /^@/
   else
     puts "Setting nameserver : #{nameserver}"
     resolver.nameserver = (nameserver.sub(/^@/, ''))
-    resolver.dnssec = true
-    resolver.do_validation = true
     puts "nameservers = #{resolver.config.nameserver}"
     zone_transfer.server = (nameserver.sub(/^@/, ''))
   end

data/dnsruby.gemspec

@@ -14,10 +14,10 @@ SPEC = Gem::Specification.new do |s|
 'Dnsruby is a pure Ruby DNS client library which implements a
 stub resolver. It aims to comply with all DNS RFCs, including
 DNSSEC NSEC3 support.'
-  s.license = "Apache License, Version 2.0"
+  s.license = "Apache-2.0"
 
   # Add explicit Ruby version requirement
-  s.required_ruby_version = '>= 2.8.0'
+  s.required_ruby_version = '>= 3.0.0'
 
   s.files = `git ls-files -z`.split("\x0")
 
@@ -40,14 +40,15 @@ DNSSEC NSEC3 support.'
 
   s.add_development_dependency 'rake', '>= 13.0.6'
   s.add_development_dependency 'minitest', '~> 5.25'
+  # Retained for the legacy localdns/test_dnsserver helpers; rake soak uses stdlib.
   s.add_development_dependency 'rubydns', '>= 2.0.2'
   s.add_development_dependency 'nio4r', '>= 2.5.8'
   s.add_development_dependency 'minitest-display', '>= 0.3.1'
   s.add_development_dependency 'rdoc', '>= 6.5', '< 8.0'
   s.add_development_dependency 'yard', '>= 0.9'
-  s.add_development_dependency 'coveralls', '~> 0.8.23'
+  s.add_development_dependency 'simplecov', '~> 0.22.0'
 
   s.add_runtime_dependency 'base64', '>= 0.2'
   s.add_runtime_dependency 'logger', '~> 1.6'
-  s.add_runtime_dependency 'simpleidn', '~> 0.2.1'
+  s.add_runtime_dependency 'simpleidn', '>= 0.2.1', '< 0.4.0'
 end