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.StreamGenerator A utility class for generating signed message responses.
static class	TSIG.StreamVerifier A utility class for verifying multiple message responses.

Field Summary

Fields

Modifier and Type	Field and Description
static Duration	FUDGE The default fudge value for outgoing packets.
static Name	GSS_TSIG The domain name representing the gss-tsig algorithm.
static Name	HMAC Deprecated. use HMAC_MD5
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(Mac mac, Name name) Deprecated. Use one of the constructors that specifies an algorithm and key.
TSIG(Name name, byte[] key) Deprecated. Use TSIG(Name, Name, SecretKey) to explicitly specify an algorithm.
TSIG(Name algorithm, Name name, byte[] keyBytes) Creates a new TSIG key, which can be used to sign or verify a message.
TSIG(Name algorithm, Name name, SecretKey key) Creates a new TSIG key, which can be used to sign or verify a message.
TSIG(Name algorithm, Name name, SecretKey key, Clock clock) Creates a new TSIG key, which can be used to sign or verify a message.
TSIG(Name algorithm, Name name, String key) Creates a new TSIG object, 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) Deprecated. Use TSIG(Name, String, String) to explicitly specify an algorithm.
TSIG(String algorithm, String name, String key) Creates a new TSIG object, which can be used to sign or verify a message.

Method Summary

Modifier and Type	Method and Description
static Name	algorithmToName(String alg) Convert an algorithm String to its equivalent Name.
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, int error, TSIGRecord old, boolean fullSignature) 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	apply(Message m, TSIGRecord old, boolean fullSignature) Generates a TSIG record with a specific error for a message and adds it to the message.
void	applyStream(Message m, TSIGRecord old, boolean fullSignature) Deprecated. use apply(Message, TSIGRecord, boolean)
static TSIG	fromString(String str) Deprecated. Use an explicit constructor
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.
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.
static String	nameToAlgorithm(Name name) Deprecated. Returns java algorithm name, will be made private in 4.0
int	recordLength() Returns the maximum length of a TSIG record generated by this key.
byte	verify(Message m, byte[] b, int length, TSIGRecord old) Deprecated. use verify(Message, byte[], TSIGRecord)
int	verify(Message m, byte[] messageBytes, TSIGRecord requestTSIG) Verifies a TSIG record on an incoming message.
int	verify(Message m, byte[] messageBytes, TSIGRecord requestTSIG, boolean fullSignature) 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

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 Detail

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:

RFC8945

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 Detail

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:

Rcode

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:

Rcode

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:

Rcode

recordLength

public int recordLength()

Returns the maximum length of a TSIG record generated by this key.

See Also:

TSIGRecord