TSIG (dnsjava documentation)
Date: 2013-04-10

org.xbill.DNS

## Class TSIG

- java.lang.Object
- - org.xbill.DNS.TSIG

-     public class TSIG
      extends Object

  Transaction signature handling. This class generates and verifies TSIG records on messages, which provide transaction security.
  Author:
    Brian Wellington
  See Also:
    `TSIGRecord`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TSIG.StreamVerifier`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static short` | `FUDGE` The default fudge value for outgoing packets.
    `static Name` | `HMAC` The domain name representing the HMAC-MD5 algorithm (deprecated).
    `static Name` | `HMAC_MD5` The domain name representing the HMAC-MD5 algorithm.
    `static Name` | `HMAC_SHA1` The domain name representing the HMAC-SHA1 algorithm.
    `static Name` | `HMAC_SHA224` The domain name representing the HMAC-SHA224 algorithm.
    `static Name` | `HMAC_SHA256` The domain name representing the HMAC-SHA256 algorithm.
    `static Name` | `HMAC_SHA384` The domain name representing the HMAC-SHA384 algorithm.
    `static Name` | `HMAC_SHA512` The domain name representing the HMAC-SHA512 algorithm.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TSIG(Name name, byte[] key)` Creates a new TSIG key with the hmac-md5 algorithm, which can be used to sign or verify a message.
    `TSIG(Name algorithm, Name name, byte[] key)` Creates a new TSIG key, which can be used to sign or verify a message.
    `TSIG(Name algorithm, String name, String key)` Creates a new TSIG object, which can be used to sign or verify a message.
    `TSIG(String name, String key)` Creates a new TSIG object with the hmac-md5 algorithm, which can be used to sign or verify a message.
    `TSIG(String algorithm, String name, String key)` Creates a new TSIG object, which can be used to sign or verify a message.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `apply(Message m, int error, TSIGRecord old)` Generates a TSIG record with a specific error for a message and adds it to the message.
    `void` | `apply(Message m, TSIGRecord old)` Generates a TSIG record for a message and adds it to the message
    `void` | `applyStream(Message m, TSIGRecord old, boolean first)` Generates a TSIG record for a message and adds it to the message
    `static TSIG` | `fromString(String str)` Creates a new TSIG object, which can be used to sign or verify a message.
    `TSIGRecord` | `generate(Message m, byte[] b, int error, TSIGRecord old)` Generates a TSIG record with a specific error for a message that has been rendered.
    `int` | `recordLength()` Returns the maximum length of a TSIG record generated by this key.
    `byte` | `verify(Message m, byte[] b, int length, TSIGRecord old)` Verifies a TSIG record on an incoming message.
    `int` | `verify(Message m, byte[] b, TSIGRecord old)` Verifies a TSIG record on an incoming message.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### HMAC_MD5

          public static final Name HMAC_MD5

      The domain name representing the HMAC-MD5 algorithm.

    - #### HMAC

          public static final Name HMAC

      The domain name representing the HMAC-MD5 algorithm (deprecated).

    - #### HMAC_SHA1

          public static final Name HMAC_SHA1

      The domain name representing the HMAC-SHA1 algorithm.

    - #### HMAC_SHA224

          public static final Name HMAC_SHA224

      The domain name representing the HMAC-SHA224 algorithm. Note that SHA224 is not supported by Java out-of-the-box, this requires use of a third party provider like BouncyCastle.org.

    - #### HMAC_SHA256

          public static final Name HMAC_SHA256

      The domain name representing the HMAC-SHA256 algorithm.

    - #### HMAC_SHA384

          public static final Name HMAC_SHA384

      The domain name representing the HMAC-SHA384 algorithm.

    - #### HMAC_SHA512

          public static final Name HMAC_SHA512

      The domain name representing the HMAC-SHA512 algorithm.

    - #### FUDGE

          public static final short FUDGE

      The default fudge value for outgoing packets. Can be overriden by the tsigfudge option.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TSIG

          public TSIG(Name algorithm,
              Name name,
              byte[] key)

      Creates a new TSIG key, which can be used to sign or verify a message.
      Parameters:
        `algorithm` - The algorithm of the shared key.
        `name` - The name of the shared key.
        `key` - The shared key's data.

    - #### TSIG

          public TSIG(Name name,
              byte[] key)

      Creates a new TSIG key with the hmac-md5 algorithm, which can be used to sign or verify a message.
      Parameters:
        `name` - The name of the shared key.
        `key` - The shared key's data.

    - #### TSIG

          public TSIG(Name algorithm,
              String name,
              String key)

      Creates a new TSIG object, which can be used to sign or verify a message.
      Parameters:
        `name` - The name of the shared key.
        `key` - The shared key's data represented as a base64 encoded string.
      Throws:
        `IllegalArgumentException` - The key name is an invalid name
        `IllegalArgumentException` - The key data is improperly encoded

    - #### TSIG

          public TSIG(String algorithm,
              String name,
              String key)

      Creates a new TSIG object, which can be used to sign or verify a message.
      Parameters:
        `name` - The name of the shared key.
        `algorithm` - The algorithm of the shared key. The legal values are "hmac-md5", "hmac-sha1", "hmac-sha224", "hmac-sha256", "hmac-sha384", and "hmac-sha512".
        `key` - The shared key's data represented as a base64 encoded string.
      Throws:
        `IllegalArgumentException` - The key name is an invalid name
        `IllegalArgumentException` - The key data is improperly encoded

    - #### TSIG

          public TSIG(String name,
              String key)

      Creates a new TSIG object with the hmac-md5 algorithm, which can be used to sign or verify a message.
      Parameters:
        `name` - The name of the shared key
        `key` - The shared key's data, represented as a base64 encoded string.
      Throws:
        `IllegalArgumentException` - The key name is an invalid name
        `IllegalArgumentException` - The key data is improperly encoded

  - ### Method Detail

    - #### fromString

          public static TSIG fromString(String str)

      Creates a new TSIG object, which can be used to sign or verify a message.
      Parameters:
        `str` - The TSIG key, in the form name:secret, name/secret, alg:name:secret, or alg/name/secret. If an algorithm is specified, it must be "hmac-md5", "hmac-sha1", or "hmac-sha256".
      Throws:
        `IllegalArgumentException` - The string does not contain both a name and secret.
        `IllegalArgumentException` - The key name is an invalid name
        `IllegalArgumentException` - The key data is improperly encoded

    - #### generate

          public TSIGRecord generate(Message m,
                            byte[] b,
                            int error,
                            TSIGRecord old)

      Generates a TSIG record with a specific error for a message that has been rendered.
      Parameters:
        `m` - The message
        `b` - The rendered message
        `error` - The error
        `old` - If this message is a response, the TSIG from the request
      Returns:
        The TSIG record to be added to the message

    - #### apply

          public void apply(Message m,
                   int error,
                   TSIGRecord old)

      Generates a TSIG record with a specific error for a message and adds it to the message.
      Parameters:
        `m` - The message
        `error` - The error
        `old` - If this message is a response, the TSIG from the request

    - #### apply

          public void apply(Message m,
                   TSIGRecord old)

      Generates a TSIG record for a message and adds it to the message
      Parameters:
        `m` - The message
        `old` - If this message is a response, the TSIG from the request

    - #### applyStream

          public void applyStream(Message m,
                         TSIGRecord old,
                         boolean first)

      Generates a TSIG record for a message and adds it to the message
      Parameters:
        `m` - The message
        `old` - If this message is a response, the TSIG from the request

    - #### verify

          public byte verify(Message m,
                    byte[] b,
                    int length,
                    TSIGRecord old)

      Verifies a TSIG record on an incoming message. Since this is only called in the context where a TSIG is expected to be present, it is an error if one is not present. After calling this routine, Message.isVerified() may be called on this message.
      Parameters:
        `m` - The message
        `b` - An array containing the message in unparsed form. This is necessary since TSIG signs the message in wire format, and we can't recreate the exact wire format (with the same name compression).
        `length` - The length of the message in the array.
        `old` - If this message is a response, the TSIG from the request
      Returns:
        The result of the verification (as an Rcode)
      See Also:
        `Rcode`

    - #### verify

          public int verify(Message m,
                   byte[] b,
                   TSIGRecord old)

      Verifies a TSIG record on an incoming message. Since this is only called in the context where a TSIG is expected to be present, it is an error if one is not present. After calling this routine, Message.isVerified() may be called on this message.
      Parameters:
        `m` - The message
        `b` - The message in unparsed form. This is necessary since TSIG signs the message in wire format, and we can't recreate the exact wire format (with the same name compression).
        `old` - If this message is a response, the TSIG from the request
      Returns:
        The result of the verification (as an Rcode)
      See Also:
        `Rcode`

    - #### recordLength

          public int recordLength()

      Returns the maximum length of a TSIG record generated by this key.
      See Also:
        `TSIGRecord`