Parent

Class Index [+]

Quicksearch

Dnsruby::RR::TSIG

TSIG implements RFC2845.

“This protocol allows for transaction level authentication using shared secrets and one way hashing. It can be used to authenticate dynamic updates as coming from an approved client, or to authenticate responses as coming from an approved recursive name server.”

A Dnsruby::RR::TSIG can represent the data present in a TSIG RR. However, it can also represent the data (specified in RFC2845) used to sign or verify a DNS message.

Example code :

    res = Dnsruby::Resolver.new("ns0.validation-test-servers.nominet.org.uk")
    
    # Now configure the resolver with the TSIG key for signing/verifying
    KEY_NAME="rubytsig"
    KEY = "8n6gugn4aJ7MazyNlMccGKH1WxD2B3UvN/O/RA6iBupO2/03u9CTa3Ewz3gBWTSBCH3crY4Kk+tigNdeJBAvrw=="
    res.tsig=KEY_NAME, KEY
    
    update = Dnsruby::Update.new("validation-test-servers.nominet.org.uk")
    # Generate update record name, and test it has been made. Then delete it and check it has been deleted
    update_name = generate_update_name
    update.absent(update_name)
    update.add(update_name, 'TXT', 100, "test signed update")
    
    # Resolver will automatically sign message and verify response
    response = res.send_message(update)
    assert(response.verified?) # Check that the response has been verified

Constants

HMAC_MD5
HMAC_SHA1
HMAC_SHA256
DEFAULT_FUDGE
DEFAULT_ALGORITHM
TypeValue

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"

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"

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"

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"

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"

original_id[RW]

Gets or sets the original message ID.

    rr.original_id(12345)
    print "original ID = ", rr.original_id, "\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"

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"

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"

key[RW]

Stores the secret key used for signing/verifying messages.

Public Instance Methods

algorithm=(alg) click to toggle source

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

  • hmac-md5

  • hmac-sha1

  • hmac-sha256

     # 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) click to toggle source

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.

    # 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) click to toggle 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) click to toggle 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() click to toggle 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) click to toggle 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() click to toggle 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="") click to toggle source

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

     # 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) click to toggle source

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# 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# is set to :Intermediate. If there is an error with the TSIG verification, then the response# 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.

     # 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

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.