Class: Dnsruby::RR::TSIG

Constants

 Name.create("HMAC-MD5.SIG-ALG.REG.INT.")
 Name.create("hmac-sha1.")
 Name.create("hmac-sha256.")
 DEFAULT_FUDGE
 HMAC_MD5
 Types::TSIG #:nodoc: all

Attributes

algorithm	[R]	Gets or sets the domain name that specifies the name of the algorithm. The only algorithms currently supported are hmac-md5 and hmac-sha1. rr.algorithm=(algorithm_name) print "algorithm = ", rr.algorithm, "\n"
error	[RW]	Returns the RCODE covering TSIG processing. Common values are NOERROR, BADSIG, BADKEY, and BADTIME. See RFC 2845 for details. print "error = ", rr.error, "\n"
fudge	[R]	Gets or sets the "fudge", i.e., the seconds of error permitted in the signing time. The default fudge is 300 seconds. rr.fudge=(60) print "fudge = ", rr.fudge, "\n"
key	[RW]	Stores the secret key used for signing/verifying messages.
mac	[RW]	Returns the message authentication code (MAC) as a string of hex characters. The programmer must call a Net::DNS::Packet object‘s data method before this will return anything meaningful. print "MAC = ", rr.mac, "\n"
mac_size	[RW]	Returns the number of octets in the message authentication code (MAC). The programmer must call a Net::DNS::Packet object‘s data method before this will return anything meaningful. print "MAC size = ", rr.mac_size, "\n"
original_id	[RW]	Gets or sets the original message ID. rr.original_id(12345) print "original ID = ", rr.original_id, "\n"
other_data	[RW]	Returns the Other Data. This field should be empty unless the error is BADTIME, in which case it will contain the server‘s time as the number of seconds since 1 Jan 1970 00:00:00 UTC. print "other data = ", rr.other_data, "\n"
other_size	[RW]	Returns the length of the Other Data. Should be zero unless the error is BADTIME. print "other len = ", rr.other_size, "\n"
time_signed	[RW]	Gets or sets the signing time as the number of seconds since 1 Jan 1970 00:00:00 UTC. The default signing time is the current time. rr.time_signed=(time) print "time signed = ", rr.time_signed, "\n"

Public Instance methods

algorithm=(alg)

Set the algorithm to use to generate the HMAC Supported values are :

hmac-md5
hmac-sha1
hmac-sha256

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 518
518:       def algorithm=(alg)
519:         if (alg.class == String)
520:           if (alg.downcase=="hmac-md5")
521:             @algorithm = HMAC_MD5;
522:           elsif (alg.downcase=="hmac-sha1")
523:             @algorithm = HMAC_SHA1;
524:           elsif (alg.downcase=="hmac-sha256")
525:             @algorithm = HMAC_SHA256;
526:           else
527:             raise ArgumentError.new("Invalid TSIG algorithm")
528:           end
529:         elsif (alg.class == Name)
530:           if (alg!=HMAC_MD5 && alg!=HMAC_SHA1 && alg!=HMAC_SHA256)
531:             raise ArgumentException.new("Invalid TSIG algorithm")
532:           end
533:           @algorithm=alg
534:         else
535:           raise ArgumentError.new("#{alg.class} not valid type for Dnsruby::RR::TSIG#algorithm=  - use String or Name")
536:         end
537:         Dnsruby.log.debug{"Using #{@algorithm.to_s} algorithm"}
538:       end

apply(message, original_request=nil)

Generates a TSIG record and adds it to the message. Takes an optional original_request argument for the case where this is a response to a query (RFC2845 3.4.1)

Message#tsigstate will be set to :Signed.

[Source]

    # File lib/Dnsruby/resource/TSIG.rb, line 67
67:       def apply(message, original_request=nil)
68:         if (!message.signed?)
69:           tsig_rr = generate(message, original_request)
70:           message.add_additional(tsig_rr)
71:           message.tsigstate = :Signed
72:           @query = message
73:           tsig_rr.query = message
74:         end
75:       end

calculate_mac(algorithm, data)

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 143
143:       def calculate_mac(algorithm, data)
144:         mac=nil
145: #+ if (key_size > max_digest_len) {

146: #+   EVP_DigestInit(&ectx, digester);

147: #+   EVP_DigestUpdate(&ectx, (const void*) key_bytes, key_size);

148: #+   EVP_DigestFinal(&ectx, key_bytes, NULL);

149: #+   key_size = max_digest_len;

150: #+ }

151:         key = @key.gsub(" ", "")
152:  #       key = Base64::decode64(key)

153:         key = key.unpack("m*")[0]
154:         if (algorithm.to_s.downcase == HMAC_MD5.to_s.downcase)
155:           mac = OpenSSL::HMAC.digest(OpenSSL::Digest::MD5.new, key, data)
156:         elsif (algorithm == HMAC_SHA1)
157:           mac = OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, key, data)
158:         elsif (algorithm == HMAC_SHA256)
159:           mac = OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, key, data)
160:         else
161:           # Should we allow client to pass in their own signing function?

162:           raise VerifyError.new("Algorithm #{algorithm} unsupported by TSIG")
163:         end
164:         return mac
165:       end

fudge=(f)

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 540
540:       def fudge=(f)
541:         if (f < 0 || f > 0x7FFF)
542:           @fudge = DEFAULT_FUDGE
543:         else
544:           @fudge = f
545:         end
546:       end

init_defaults()

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 466
466:       def init_defaults
467:         # @TODO@ Have new() method which takes key_name and key?

468:         @algorithm   = DEFAULT_ALGORITHM
469:         @fudge       = DEFAULT_FUDGE
470:         @mac_size    = 0
471:         @mac         = ""
472:         @original_id = rand(65536)
473:         @error       = 0
474:         @other_size   = 0
475:         @other_data  = ""
476:         @time_signed = nil
477:         @buf = nil
478:         
479:         # RFC 2845 Section 2.3

480:         @klass = "ANY"
481:         
482:         @ttl = 0 # RFC 2845 Section 2.3

483:       end

name=(n)

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 489
489:       def name=(n)
490:         if (n.instance_of?String)
491:           n = Name.create(n)
492:         end
493:         if (!n.absolute?)
494:           @name = Name.create(n.to_s + ".")
495:         else 
496:           @name = n
497:         end
498:       end

rdata_to_string()

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 548
548:       def rdata_to_string        
549:         rdatastr=""
550:         if (@algorithm!=nil)
551:           error = @error
552:           error = "UNDEFINED" unless error!=nil
553:           rdatastr = "#{@original_id} #{@time_signed} #{@algorithm.to_s(true)} #{error}";
554:           if (@other_size > 0 && @other_data!=nil)
555:             rdatastr += " #{@other_data}"
556:           end
557:           rdatastr += " " + mac.unpack("H*").to_s
558:         end
559:         
560:         return rdatastr
561:       end

verify(query, response, response_bytes, buf="")

Verify a response. This method will be called by Dnsruby::SingleResolver before passing a response to the client code. The TSIG record will be removed from packet before passing to client, and the Message#tsigstate and Message#tsigerror will be set accordingly. Message#tsigstate will be set to one of :

:Failed
:Verified

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 191
191:       def verify(query, response, response_bytes, buf="")
192:         #        4.6. Client processing of answer

193:         #

194:         #   When a client receives a response from a server and expects to see a

195:         #   TSIG, it first checks if the TSIG RR is present in the response.

196:         #   Otherwise, the response is treated as having a format error and

197:         #   discarded.  The client then extracts the TSIG, adjusts the ARCOUNT,

198:         #   and calculates the keyed digest in the same way as the server.  If

199:         #   the TSIG does not validate, that response MUST be discarded, unless

200:         #   the RCODE is 9 (NOTAUTH), in which case the client SHOULD attempt to

201:         #   verify the response as if it were a TSIG Error response, as specified

202:         #   in [4.3].  A message containing an unsigned TSIG record or a TSIG

203:         #   record which fails verification SHOULD not be considered an

204:         #   acceptable response; the client SHOULD log an error and continue to

205:         #   wait for a signed response until the request times out.

206: 
207:         # So, this verify method should simply remove the TSIG RR and calculate

208:         # the MAC (using original request MAC if required).

209:         # Should set tsigstate on packet appropriately, and return error.

210:         # Side effect is packet is stripped of TSIG.

211:         # Resolver (or client) can then decide what to do...

212: 
213:         msg_tsig_rr = response.tsig
214:         if (!verify_common(response))
215:           return false
216:         end
217: 
218:         new_msg_tsig_rr = generate(response, query, buf, response_bytes, msg_tsig_rr)
219:         
220:         if (msg_tsig_rr.mac == new_msg_tsig_rr.mac)
221:           response.tsigstate = :Verified
222:           response.tsigerror = RCode.NOERROR
223:           return true
224:         else
225:           response.tsigstate = :Failed
226:           response.tsigerror = RCode.BADSIG
227:           return false
228:         end
229:       end

verify_envelope(response, response_bytes)

Checks TSIG signatures across sessions of multiple DNS envelopes. This method is called each time a new envelope comes in. The envelope is checked - if a TSIG is present, them the stream so far is verified, and the response#tsigstate set to :Verified. If a TSIG is not present, and does not need to be present, then the message is added to the digest stream and the response#tsigstate is set to :Intermediate. If there is an error with the TSIG verification, then the response#tsigstate is set to :Failed. Like verify, this method will only be called by the Dnsruby::SingleResolver class. Client code need not call this method directly.

[Source]

     # File lib/Dnsruby/resource/TSIG.rb, line 279
279:       def verify_envelope(response, response_bytes)
280:         #RFC2845 Section 4.4

281:         #-----

282:         #A DNS TCP session can include multiple DNS envelopes.  This is, for

283:         #example, commonly used by zone transfer.  Using TSIG on such a

284:         #connection can protect the connection from hijacking and provide data

285:         #integrity.  The TSIG MUST be included on the first and last DNS

286:         #envelopes.  It can be optionally placed on any intermediary

287:         #envelopes.  It is expensive to include it on every envelopes, but it

288:         #MUST be placed on at least every 100'th envelope.  The first envelope

289:         #is processed as a standard answer, and subsequent messages have the

290:         #following digest components:

291:         #

292:         #*   Prior Digest (running)

293:         #*   DNS Messages (any unsigned messages since the last TSIG)

294:         #*   TSIG Timers (current message)

295:         #

296:         #This allows the client to rapidly detect when the session has been

297:         #altered; at which point it can close the connection and retry.  If a

298:         #client TSIG verification fails, the client MUST close the connection.

299:         #If the client does not receive TSIG records frequently enough (as

300:         #specified above) it SHOULD assume the connection has been hijacked

301:         #and it SHOULD close the connection.  The client SHOULD treat this the

302:         #same way as they would any other interrupted transfer (although the

303:         #exact behavior is not specified).

304:         #-----

305:         #

306:         # Each time a new envelope comes in, this method is called on the QUERY TSIG RR.

307:         # It will set the response tsigstate to :Verified :Intermediate or :Failed

308:         # as appropriate.

309:         
310:         # Keep digest going of messages as they come in (and mark them intermediate)

311:         # When TSIG comes in, work out what key should be and check. If OK, mark 

312:         # verified. Can reset digest then.

313:         if (!@buf)
314:           @num_envelopes = 0
315:           @last_signed = 0
316:         end
317:         @num_envelopes += 1
318:         if (!response.tsig)
319:           if ((@num_envelopes > 1) && (@num_envelopes - @last_signed < 100))
320:             Dnsruby.log.debug("Receiving intermediate envelope in TSIG TCP session")
321:             response.tsigstate = :Intermediate
322:             response.tsigerror = RCode.NOERROR
323:             @buf = @buf + response_bytes
324:             return
325:           else
326:             response.tsigstate = :Failed
327:             Dnsruby.log.error("Expecting signed packet")
328:             return false
329:           end
330:         end
331:         @last_signed = @num_envelopes
332:         
333:         # We have a TSIG - process it!

334:         tsig = response.tsig
335:         if (@num_envelopes == 1)
336:           Dnsruby.log.debug("First response in TSIG TCP session - verifying normally")
337:           # Process it as a standard answer

338:           ok = verify(@query, response, response_bytes)
339:           if (ok)
340:             mac_bytes = MessageEncoder.new {|m|
341:               m.put_pack('n', tsig.mac_size)
342:               m.put_bytes(tsig.mac)
343:             }.to_s
344:             @buf = mac_bytes
345:           end
346:           return ok
347:         end
348:         Dnsruby.log.debug("Processing TSIG on TSIG TCP session")
349: 
350:         if (!verify_common(response))
351:           return false
352:         end
353:         
354:         # Now add the current message data - remember to frig the arcount

355:         response_bytes = Header.decrement_arcount_encoded(response_bytes)
356:         @buf += response_bytes[0, response.tsigstart]
357:         
358:         # Let's add the timers

359:         timers_data = MessageEncoder.new { |msg|
360:           time_high = (tsig.time_signed >> 32)
361:           time_low = (tsig.time_signed & 0xFFFFFFFF)
362:           msg.put_pack('nN', time_high, time_low)
363:           msg.put_pack('n', tsig.fudge)
364:         }.to_s
365:         @buf += timers_data
366:         
367:         mac = calculate_mac(tsig.algorithm, @buf)
368: 
369:         if (mac != tsig.mac)
370:           Dnsruby.log.error("TSIG Verify error on TSIG TCP session")
371:           response.tsigstate = :Failed
372:           return false
373:         end
374:         mac_bytes = MessageEncoder.new {|m|
375:           m.put_pack('n', mac.length)
376:           m.put_bytes(mac)
377:         }.to_s
378:         @buf=mac_bytes
379: 
380:         response.tsigstate = :Verified
381:         response.tsigerror = RCode.NOERROR
382:         return true
383:       end

Methods

Constants

Attributes

Public Instance methods