Class | Dnsruby::RR::TSIG |
In: |
lib/Dnsruby/resource/TSIG.rb
|
Parent: | RR |
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
HMAC_MD5 | = | Name.create("HMAC-MD5.SIG-ALG.REG.INT.") |
HMAC_SHA1 | = | Name.create("hmac-sha1.") |
HMAC_SHA256 | = | Name.create("hmac-sha256.") |
DEFAULT_FUDGE | = | 300 |
DEFAULT_ALGORITHM | = | HMAC_MD5 |
TypeValue | = | Types::TSIG #:nodoc: all |
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" |
Set the algorithm to use to generate the HMAC Supported values are :
# 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
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
# 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
# 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
# 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
# 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
# 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 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 :
# 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
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.
# 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