Package 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:

  • Field Details

    • GSS_TSIG

      public static final Name GSS_TSIG
      The domain name representing the gss-tsig algorithm.

    • HMAC_MD5

      public static final Name HMAC_MD5
      The domain name representing the HMAC-MD5 algorithm.

    • HMAC

      @Deprecated public static final Name HMAC
      Deprecated.
      use HMAC_MD5
      The domain name representing the HMAC-MD5 algorithm.

    • 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.

    • 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 Duration FUDGE
      The default fudge value for outgoing packets. Can be overridden by the tsigfudge option.

  • Constructor Details

    • TSIG

      public TSIG(Name algorithm, Name 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
      NullPointerException - key is null
      Since:
      3.2

    • TSIG

      public TSIG(Name algorithm, Name name, byte[] keyBytes)
      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.
      keyBytes - The shared key's data.

    • TSIG

      public TSIG(Name algorithm, Name name, SecretKey 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.

    • TSIG

      public TSIG(Name algorithm, Name name, SecretKey key, Clock clock)
      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.
      Since:
      3.2

    • TSIG

      @Deprecated public TSIG(Mac mac, Name name)
      Deprecated.
      Use one of the constructors that specifies an algorithm and key.
      Creates a new TSIG key from a pre-initialized Mac instance. This assumes that init() has already been called on the mac to set up the key.
      Parameters:
      mac - The JCE HMAC object
      name - The name of the key

    • TSIG

      @Deprecated public TSIG(Name name, byte[] key)
      Deprecated.
      Use TSIG(Name, Name, SecretKey) to explicitly specify an algorithm.
      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:
      algorithm - The RFC8945 algorithm name of the shared key. The legal values are:
      • hmac-md5.sig-alg.reg.int.
      • hmac-md5. (alias for hmac-md5.sig-alg.reg.int.)
      • hmac-sha1.
      • hmac-sha224.
      • hmac-sha256.
      • hmac-sha384.
      • hmac-sha512.
      The trailing "." can be omitted.
      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
      See Also:

    • TSIG

      @Deprecated public TSIG(String name, String key)
      Deprecated.
      Use TSIG(Name, String, String) to explicitly specify an algorithm.
      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 Details

    • algorithmToName

      public static Name algorithmToName(String alg)
      Convert an algorithm String to its equivalent Name.
      Parameters:
      alg - String containing name of algorithm.
      Returns:
      Name object for algorithm
      Throws:
      IllegalArgumentException - The algorithm is null or invalid.

    • nameToAlgorithm

      @Deprecated public static String nameToAlgorithm(Name name)
      Deprecated.
      Returns java algorithm name, will be made private in 4.0
      Convert an algorithm Name to a string.
      Parameters:
      name - Name object
      Returns:
      String equivalent

    • fromString

      @Deprecated public static TSIG fromString(String str)
      Deprecated.
      Use an explicit constructor
      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 no algorithm is specified, the default of HMAC_MD5 is used.
      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

    • generate

      public TSIGRecord generate(Message m, byte[] b, int error, TSIGRecord old, boolean fullSignature)
      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
      fullSignature - true if this TSIGRecord is the to be added to the first of many messages in a TCP connection and all TSIG variables (rfc2845, 3.4.2.) should be included in the signature. false for subsequent messages with reduced TSIG variables set (rfc2845, 4.4.).
      Returns:
      The TSIG record to be added to the message
      Since:
      3.2

    • 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

    • 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, boolean fullSignature)
      Generates a TSIG record with a specific error 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
      fullSignature - true if this message is the first of many in a TCP connection and all TSIG variables (rfc2845, 3.4.2.) should be included in the signature. false for subsequent messages with reduced TSIG variables set (rfc2845, 4.4.).
      Since:
      3.2

    • apply

      public void apply(Message m, int error, TSIGRecord old, boolean fullSignature)
      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
      fullSignature - true if this message is the first of many in a TCP connection and all TSIG variables (rfc2845, 3.4.2.) should be included in the signature. false for subsequent messages with reduced TSIG variables set (rfc2845, 4.4.).
      Since:
      3.2

    • applyStream

      @Deprecated public void applyStream(Message m, TSIGRecord old, boolean fullSignature)
      Deprecated.
      use apply(Message, TSIGRecord, boolean)
      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
      fullSignature - true if this message is the first of many in a TCP connection and all TSIG variables (rfc2845, 3.4.2.) should be included in the signature. false for subsequent messages with reduced TSIG variables set (rfc2845, 4.4.).

    • verify

      @Deprecated public byte verify(Message m, byte[] b, int length, TSIGRecord old)
      Deprecated.
      use verify(Message, byte[], TSIGRecord)
      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.

      Use TSIG.StreamVerifier to validate multiple messages in a stream.

      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 - unused
      old - If this message is a response, the TSIG from the request
      Returns:
      The result of the verification (as an Rcode)
      See Also:

    • verify

      public int verify(Message m, byte[] messageBytes, TSIGRecord requestTSIG)
      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.

      Use TSIG.StreamVerifier to validate multiple messages in a stream.

      Parameters:
      m - The message to verify
      messageBytes - 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).
      requestTSIG - If this message is a response, the TSIG from the request
      Returns:
      The result of the verification (as an Rcode)
      See Also:

    • verify

      public int verify(Message m, byte[] messageBytes, TSIGRecord requestTSIG, boolean fullSignature)
      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.

      Use TSIG.StreamVerifier to validate multiple messages in a stream.

      Parameters:
      m - The message to verify
      messageBytes - 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).
      requestTSIG - If this message is a response, the TSIG from the request
      fullSignature - true if this message is the first of many in a TCP connection and all TSIG variables (rfc2845, 3.4.2.) should be included in the signature. false for subsequent messages with reduced TSIG variables set (rfc2845, 4.4.).
      Returns:
      The result of the verification (as an Rcode)
      Since:
      3.2
      See Also:

    • recordLength

      public int recordLength()
      Returns the maximum length of a TSIG record generated by this key.
      See Also: