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.
See Also:

  • Field Details

    • GSS_TSIG

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

    • HMAC_MD5

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

    • HMAC

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

    • HMAC_SHA1

      public static final Name HMAC_SHA1
      The domain name representing the HMAC-SHA1 algorithm.
      See Also:

    • HMAC_SHA224

      public static final Name HMAC_SHA224
      The domain name representing the HMAC-SHA224 algorithm.
      See Also:

    • HMAC_SHA256

      public static final Name HMAC_SHA256
      The domain name representing the HMAC-SHA256 algorithm.
      See Also:

    • HMAC_SHA384

      public static final Name HMAC_SHA384
      The domain name representing the HMAC-SHA384 algorithm.
      See Also:

    • HMAC_SHA512

      public static final Name HMAC_SHA512
      The domain name representing the HMAC-SHA512 algorithm.
      See Also:

    • HMAC_SHA256_128

      public static final Name HMAC_SHA256_128
      The domain name representing the HMAC-SHA256-128 algorithm.
      Since:
      3.6.3
      See Also:

    • HMAC_SHA384_192

      public static final Name HMAC_SHA384_192
      The domain name representing the HMAC-SHA384-192 algorithm.
      Since:
      3.6.3
      See Also:

    • HMAC_SHA512_256

      public static final Name HMAC_SHA512_256
      The domain name representing the HMAC-SHA512-256 algorithm.
      Since:
      3.6.3
      See Also:

    • algMap

      private static final Map<Name,String> algMap

    • algLengthMap

      private static final Map<Name,Integer> algLengthMap

    • javaAlgNamePattern

      private static final Pattern javaAlgNamePattern

    • FUDGE

      public static final Duration FUDGE
      The default fudge value for outgoing packets. Can be overridden by the tsigfudge option.

    • alg

      private final Name alg

    • clock

      private final Clock clock

    • name

      private final Name name

    • macKey

      private final SecretKey macKey

    • macAlgorithm

      private final String macAlgorithm

    • sharedHmac

      private final Mac sharedHmac

  • 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-sha256-128.
      • hmac-sha384.
      • hmac-sha384-192.
      • hmac-sha512.
      • hmac-sha512-256.
      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

    • verify

      private static boolean verify(byte[] expected, byte[] signature)
      Verifies the data (computes the secure hash and compares it to the input)
      Parameters:
      expected - The expected (locally calculated) signature
      signature - The signature to compare against
      Returns:
      true if the signature matches, false otherwise

    • initHmac

      private Mac initHmac()

    • 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

    • generate

      private TSIGRecord generate(Message m, byte[] b, int error, TSIGRecord old, boolean fullSignature, Mac hmac)
      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.).
      hmac - A mac instance to reuse for a stream of messages to sign, e.g. when doing a zone transfer.
      Returns:
      The TSIG record to be added to the message

    • getTimeSigned

      private Instant getTimeSigned(int error, TSIGRecord old)

    • getTsigFudge

      private static Duration getTsigFudge()

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

    • verify

      private int verify(Message m, byte[] messageBytes, TSIGRecord requestTSIG, boolean fullSignature, Mac hmac)
      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 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)
      See Also:

    • getTsigVariables

      private static byte[] getTsigVariables(boolean fullSignature, TSIGRecord tsig)

    • verifySignature

      private int verifySignature(Mac hmac, byte[] signature)

    • verifyTime

      private int verifyTime(TSIGRecord tsig)

    • recordLength

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

    • hmacAddSignature

      private static void hmacAddSignature(Mac hmac, TSIGRecord tsig)

    • writeTsigTimerVariables

      private static void writeTsigTimerVariables(Instant instant, Duration fudge, DNSOutput out)

    • writeTsigTime

      private static void writeTsigTime(Instant instant, DNSOutput out)