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

Methods

Constants

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

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

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

  • hmac-md5
  • hmac-sha1
  • hmac-sha256

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.

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

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.

[Validate]